@xpert-ai/chatkit-types 0.19.1 → 0.20.1

package/dist/index.d.ts

@@ -418,8 +418,18 @@ export declare type ChatKitEvents = {
         threadId: string;
     }>;
     /** Emitted when ChatKit finished loading a thread. */
+    /** Metadata for the loaded branch; excludes messages, resources and execution internals. */
     'chatkit.thread.load.end': CustomEvent<{
         threadId: string;
+        conversation?: {
+            id: string;
+            threadId: string;
+            title?: string;
+            projectId?: string;
+            xpertId?: string;
+            from?: string;
+            status?: 'idle' | 'busy' | 'pausing' | 'paused' | 'interrupted' | 'error';
+        };
     }>;
     /** Diagnostic events that can be used for logging/analytics. */
     'chatkit.log': CustomEvent<{
@@ -696,6 +706,11 @@ export declare type ChatKitOptions = {
      */
     header?: {
         enabled?: boolean;
+        /** Inline avatar, title, and status block. Hidden by default; separate from the centered character. */
+        identity?: {
+            /** Show the identity block when the centered character is not displayed. Defaults to false. */
+            enabled?: boolean;
+        };
         /** Center the published Assistant character in bubble mode. Defaults to true. */
         character?: {
             enabled?: boolean;
@@ -2083,6 +2098,8 @@ export declare function isHITLRequest(value: unknown): value is HITLRequest;
 
 export declare function isHITLReviewDisplay(value: unknown): value is HITLReviewDisplay;
 
+export declare function isInputDate(value: unknown): value is string;
+
 export declare function isInterruptRequest(value: unknown): value is InterruptRequest;
 
 export declare function isLangGraphInterrupt(value: unknown): value is LangGraphInterrupt;
@@ -2091,6 +2108,8 @@ export declare function isLangGraphInterruptPayload(value: unknown): value is La
 
 export declare function isLangGraphInterruptTask(value: unknown): value is LangGraphInterruptTask;
 
+export declare function isRequestUserInputForm(value: unknown): value is RequestUserInputForm;
+
 export declare function isResourceCardContent(value: unknown): boolean;
 
 export declare function isToolCallInterrupt(value: unknown): value is ToolCallInterrupt;
@@ -2436,6 +2455,16 @@ export declare interface RequestUserInputAnswer {
 
 export declare type RequestUserInputAnswerType = 'option' | 'other';
 
+export declare interface RequestUserInputForm {
+    schemaVersion: 1;
+    mode: UserInputMode;
+    purpose: 'clarification';
+    title: string;
+    description?: string;
+    fields: UserInputField[];
+    questions?: never;
+}
+
 export declare interface RequestUserInputOption {
     label: string;
     description: string;
@@ -2456,13 +2485,18 @@ export declare interface RequestUserInputResult {
     type: RequestUserInputResultType;
     purpose: RequestUserInputResultPurpose;
     answers: RequestUserInputAnswer[];
+    status?: 'submitted' | 'cancelled';
+    schemaVersion?: 1;
+    requestId?: string;
+    values?: UserInputValues;
+    form?: RequestUserInputForm;
 }
 
-export declare type RequestUserInputResultPurpose = typeof REQUEST_USER_INPUT_RESULT_PURPOSE_PLAN_CLARIFICATION | typeof REQUEST_USER_INPUT_RESULT_PURPOSE_IMPLEMENTATION_CONFIRMATION;
+export declare type RequestUserInputResultPurpose = 'clarification' | typeof REQUEST_USER_INPUT_RESULT_PURPOSE_PLAN_CLARIFICATION | typeof REQUEST_USER_INPUT_RESULT_PURPOSE_IMPLEMENTATION_CONFIRMATION;
 
 export declare type RequestUserInputResultType = typeof REQUEST_USER_INPUT_RESULT_TYPE;
 
-export declare type RequestUserInputToolArgs = RequestUserInputParams;
+export declare type RequestUserInputToolArgs = RequestUserInputParams | RequestUserInputForm;
 
 export declare type RequestUserInputToolCall = ToolCall & {
     name: RequestUserInputToolName;
@@ -3371,8 +3405,175 @@ export declare function upsertFileActivityContent<T>(content: T[], receipt: TMes
 /** Identity is local to one reply. Repeat emissions replace the snapshot in place. */
 export declare function upsertResourceCardContent<T>(parts: T[], card: TMessageContentResourceCard): (T | TMessageContentResourceCard)[];
 
+export declare const USER_INPUT_FORM_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schemaVersion", "mode", "purpose", "title", "fields"];
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly type: "integer";
+            readonly const: 1;
+        };
+        readonly mode: {
+            readonly type: "string";
+            readonly enum: readonly ["blocking"];
+        };
+        readonly purpose: {
+            readonly type: "string";
+            readonly const: "clarification";
+        };
+        readonly title: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 160;
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly maxLength: 2000;
+        };
+        readonly fields: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly maxItems: 12;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["id", "type", "label"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly pattern: "^[a-zA-Z][a-zA-Z0-9_]{0,63}$";
+                    };
+                    readonly type: {
+                        readonly type: "string";
+                        readonly enum: readonly ["text", "textarea", "number", "select", "multiselect", "boolean", "date", "date_range"];
+                    };
+                    readonly label: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 160;
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                        readonly maxLength: 2000;
+                    };
+                    readonly required: {
+                        readonly type: "boolean";
+                    };
+                    readonly options: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly maxItems: 100;
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["value", "label"];
+                            readonly properties: {
+                                readonly value: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly maxLength: 160;
+                                };
+                                readonly label: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly maxLength: 160;
+                                };
+                            };
+                        };
+                    };
+                    readonly min: {
+                        readonly type: "number";
+                    };
+                    readonly max: {
+                        readonly type: "number";
+                    };
+                    readonly minLength: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                        readonly maximum: 100000;
+                    };
+                    readonly maxLength: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                        readonly maximum: 100000;
+                    };
+                    readonly minItems: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                        readonly maximum: 100;
+                    };
+                    readonly maxItems: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                        readonly maximum: 100;
+                    };
+                };
+            };
+        };
+    };
+};
+
+export declare const USER_INPUT_SUPPORTED_MODES: readonly UserInputMode[];
+
+export declare type UserInputAnswerDeliveryStatus = 'queued' | 'applied' | 'failed';
+
+export declare interface UserInputField {
+    id: string;
+    type: 'text' | 'textarea' | 'number' | 'select' | 'multiselect' | 'boolean' | 'date' | 'date_range';
+    label: string;
+    description?: string;
+    required?: boolean;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+}
+
+/** Versioned input collection. Non-blocking delivery is reserved, not enabled. */
+export declare type UserInputMode = 'blocking' | 'non_blocking';
+
+export declare type UserInputRequestStatus = 'pending' | 'answered' | 'cancelled' | 'superseded' | 'expired';
+
+/** Future async replies are human messages, never a second tool result. */
+export declare interface UserInputResponseMetadata {
+    kind: 'user_input_response';
+    requestId: string;
+    schemaVersion: 1;
+    answers: UserInputValues;
+}
+
+export declare type UserInputValidation = {
+    valid: true;
+    values: UserInputValues;
+} | {
+    valid: false;
+    errors: {
+        [fieldId: string]: UserInputValidationError;
+    };
+};
+
+export declare type UserInputValidationError = 'required' | 'type' | 'range' | 'choice' | 'length' | 'date' | 'unknown';
+
+export declare type UserInputValue = string | number | boolean | string[] | {
+    start: string;
+    end: string;
+};
+
+export declare type UserInputValues = {
+    [fieldId: string]: UserInputValue;
+};
+
 export declare type UserMessageContent = unknown;
 
+export declare function validateUserInputValues(form: RequestUserInputForm, input: unknown): UserInputValidation;
+
 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;
 
 export declare type WidgetIcon = 'agent' | 'analytics' | 'atom' | 'batch' | 'bolt' | 'book-open' | 'book-closed' | 'book-clock' | 'bug' | 'calendar' | 'chart' | 'check' | 'check-circle' | 'check-circle-filled' | 'chevron-left' | 'chevron-right' | 'circle-question' | 'compass' | 'confetti' | 'cube' | 'desktop' | 'document' | 'dot' | 'dots-horizontal' | 'dots-vertical' | 'empty-circle' | 'external-link' | 'globe' | 'keys' | 'lab' | 'images' | 'info' | 'lifesaver' | 'lightbulb' | 'mail' | 'map-pin' | 'maps' | 'mobile' | 'name' | 'notebook' | 'notebook-pencil' | 'page-blank' | 'phone' | 'play' | 'plus' | 'profile' | 'profile-card' | 'reload' | 'star' | 'star-filled' | 'search' | 'sparkle' | 'sparkle-double' | 'square-code' | 'square-image' | 'square-text' | 'suitcase' | 'settings-slider' | 'user' | 'wreath' | 'write' | 'write-alt' | 'write-alt2';

package/dist/index.js

@@ -241,6 +241,195 @@ function isHITLReviewDisplay(value) {
     }
   });
 }
+const USER_INPUT_SUPPORTED_MODES = [
+  "blocking"
+];
+const USER_INPUT_FORM_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["schemaVersion", "mode", "purpose", "title", "fields"],
+  properties: {
+    schemaVersion: { type: "integer", const: 1 },
+    mode: { type: "string", enum: ["blocking"] },
+    purpose: { type: "string", const: "clarification" },
+    title: { type: "string", minLength: 1, maxLength: 160 },
+    description: { type: "string", maxLength: 2e3 },
+    fields: {
+      type: "array",
+      minItems: 1,
+      maxItems: 12,
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["id", "type", "label"],
+        properties: {
+          id: { type: "string", pattern: "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" },
+          type: {
+            type: "string",
+            enum: [
+              "text",
+              "textarea",
+              "number",
+              "select",
+              "multiselect",
+              "boolean",
+              "date",
+              "date_range"
+            ]
+          },
+          label: { type: "string", minLength: 1, maxLength: 160 },
+          description: { type: "string", maxLength: 2e3 },
+          required: { type: "boolean" },
+          options: {
+            type: "array",
+            minItems: 1,
+            maxItems: 100,
+            items: {
+              type: "object",
+              additionalProperties: false,
+              required: ["value", "label"],
+              properties: {
+                value: { type: "string", minLength: 1, maxLength: 160 },
+                label: { type: "string", minLength: 1, maxLength: 160 }
+              }
+            }
+          },
+          min: { type: "number" },
+          max: { type: "number" },
+          minLength: { type: "integer", minimum: 0, maximum: 1e5 },
+          maxLength: { type: "integer", minimum: 0, maximum: 1e5 },
+          minItems: { type: "integer", minimum: 0, maximum: 100 },
+          maxItems: { type: "integer", minimum: 0, maximum: 100 }
+        }
+      }
+    }
+  }
+};
+function boundedText(value, max) {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= max;
+}
+function isOption(value) {
+  return typeof value === "object" && value !== null && "value" in value && boundedText(value.value, 160) && "label" in value && boundedText(value.label, 160) && Object.keys(value).every((key) => key === "value" || key === "label");
+}
+function isField(value) {
+  if (!value || typeof value !== "object" || !("id" in value) || typeof value.id !== "string" || !/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(value.id) || ["constructor", "prototype", "__proto__"].includes(value.id) || !("type" in value) || typeof value.type !== "string" || ![
+    "text",
+    "textarea",
+    "number",
+    "select",
+    "multiselect",
+    "boolean",
+    "date",
+    "date_range"
+  ].includes(value.type) || !("label" in value) || !boundedText(value.label, 160))
+    return false;
+  if (Object.keys(value).some(
+    (key) => !Object.hasOwn(
+      USER_INPUT_FORM_SCHEMA.properties.fields.items.properties,
+      key
+    )
+  ))
+    return false;
+  if ("description" in value && (typeof value.description !== "string" || value.description.length > 2e3))
+    return false;
+  if ("required" in value && typeof value.required !== "boolean") return false;
+  if ("options" in value && (!Array.isArray(value.options) || value.options.length < 1 || value.options.length > 100 || !value.options.every(isOption) || new Set(value.options.map((option) => option.value)).size !== value.options.length))
+    return false;
+  if ((value.type === "select" || value.type === "multiselect") !== "options" in value)
+    return false;
+  for (const [key, limit] of [
+    ["minLength", 1e5],
+    ["maxLength", 1e5],
+    ["minItems", 100],
+    ["maxItems", 100]
+  ]) {
+    if (key in value) {
+      const bound = Reflect.get(value, key);
+      if (typeof bound !== "number" || !Number.isInteger(bound) || bound < 0 || bound > limit)
+        return false;
+      if (key === "minItems" || key === "maxItems" ? value.type !== "multiselect" : !["text", "textarea"].includes(value.type))
+        return false;
+    }
+  }
+  for (const key of ["min", "max"]) {
+    if (key in value && (value.type !== "number" || typeof Reflect.get(value, key) !== "number" || !Number.isFinite(Reflect.get(value, key))))
+      return false;
+  }
+  for (const [min, max] of [
+    ["min", "max"],
+    ["minLength", "maxLength"],
+    ["minItems", "maxItems"]
+  ]) {
+    if (min in value && max in value && Reflect.get(value, min) > Reflect.get(value, max))
+      return false;
+  }
+  return true;
+}
+function isRequestUserInputForm(value) {
+  return !!value && typeof value === "object" && "schemaVersion" in value && value.schemaVersion === 1 && "mode" in value && (value.mode === "blocking" || value.mode === "non_blocking") && "purpose" in value && value.purpose === "clarification" && "title" in value && boundedText(value.title, 160) && (!("description" in value) || typeof value.description === "string" && value.description.length <= 2e3) && "fields" in value && Array.isArray(value.fields) && value.fields.length > 0 && value.fields.length <= 12 && value.fields.every(isField) && new Set(value.fields.map((field) => field.id)).size === value.fields.length && Object.keys(value).every(
+    (key) => Object.hasOwn(USER_INPUT_FORM_SCHEMA.properties, key)
+  );
+}
+function isInputDate(value) {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+    return false;
+  const date = /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
+  return Number.isFinite(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+function validateField(field, value) {
+  var _a;
+  if (value === void 0 || value === "")
+    return field.required ? "required" : null;
+  if (Array.isArray(value) && value.length === 0 && field.required)
+    return "required";
+  switch (field.type) {
+    case "text":
+    case "textarea":
+      if (typeof value !== "string") return "type";
+      if (field.required && !value.trim()) return "required";
+      return value.length < (field.minLength ?? 0) || value.length > (field.maxLength ?? 1e5) ? "length" : null;
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) return "type";
+      return value < (field.min ?? -Infinity) || value > (field.max ?? Infinity) ? "range" : null;
+    case "boolean":
+      return typeof value === "boolean" ? null : "type";
+    case "select":
+      return typeof value === "string" && ((_a = field.options) == null ? void 0 : _a.some((option) => option.value === value)) ? null : "choice";
+    case "multiselect":
+      if (!Array.isArray(value) || value.some(
+        (item) => {
+          var _a2;
+          return typeof item !== "string" || !((_a2 = field.options) == null ? void 0 : _a2.some((option) => option.value === item));
+        }
+      ) || new Set(value).size !== value.length)
+        return "choice";
+      return value.length < (field.minItems ?? 0) || value.length > (field.maxItems ?? 100) ? "length" : null;
+    case "date":
+      return isInputDate(value) ? null : "date";
+    case "date_range":
+      if (!value || typeof value !== "object" || !("start" in value) || !("end" in value) || !isInputDate(value.start) || !isInputDate(value.end) || Object.keys(value).some((key) => key !== "start" && key !== "end"))
+        return "date";
+      return value.start <= value.end ? null : "range";
+  }
+}
+function validateUserInputValues(form, input) {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    return { valid: false, errors: { _form: "type" } };
+  const errors = {};
+  const values = {};
+  for (const key of Object.keys(input)) {
+    if (!form.fields.some((field) => field.id === key))
+      return { valid: false, errors: { _form: "unknown" } };
+  }
+  for (const field of form.fields) {
+    const value = Object.hasOwn(input, field.id) ? Reflect.get(input, field.id) : void 0;
+    const error = validateField(field, value);
+    if (error) errors[field.id] = error;
+    else if (value !== void 0 && value !== "")
+      values[field.id] = value;
+  }
+  return Object.keys(errors).length ? { valid: false, errors } : { valid: true, values };
+}
 const REQUEST_USER_INPUT_TOOL_NAME = "request_user_input";
 const REQUEST_USER_INPUT_RESULT_TYPE = "request_user_input_result";
 const REQUEST_USER_INPUT_RESULT_PURPOSE_PLAN_CLARIFICATION = "plan_clarification";
@@ -1253,6 +1442,8 @@ export {
   STATE_VARIABLE_HUMAN,
   TOOL_OUTPUT_PRESENTATION_TYPE,
   TOOL_OUTPUT_PRESENTATION_VERSION,
+  USER_INPUT_FORM_SCHEMA,
+  USER_INPUT_SUPPORTED_MODES,
   chatSkillUsageKey,
   clampPetPosition,
   countFileChangeLines,
@@ -1279,10 +1470,12 @@ export {
   isHITLInterruptTask,
   isHITLRequest,
   isHITLReviewDisplay,
+  isInputDate,
   isInterruptRequest,
   isLangGraphInterrupt,
   isLangGraphInterruptPayload,
   isLangGraphInterruptTask,
+  isRequestUserInputForm,
   isResourceCardContent,
   isToolCallInterrupt,
   isToolCallInterruptPayload,
@@ -1311,6 +1504,7 @@ export {
   resolvePetCharacter,
   resourceCardId,
   upsertFileActivityContent,
-  upsertResourceCardContent
+  upsertResourceCardContent,
+  validateUserInputValues
 };
 //# sourceMappingURL=index.js.map