@xpert-ai/chatkit-types 0.6.2 → 0.7.0

package/dist/index.d.ts

@@ -19,6 +19,23 @@ export declare interface AgentPluginDiagnostic {
 
 declare type Alignment = 'start' | 'center' | 'end' | 'baseline' | 'stretch';
 
+export declare interface ApprovalActionRequest {
+    request: HITLRequest;
+    action: 'settings';
+}
+
+export declare interface ApprovalDecisionRequest {
+    request: HITLRequest;
+    decisions: HITLDecision[];
+}
+
+/** Opaque host resource reference; ChatKit never interprets resource-specific policy. */
+export declare interface ApprovalHostReference {
+    kind: string;
+    id: string;
+    expiresAt: number;
+}
+
 /**
  * strategies to host files before attaching them to messages.
  */
@@ -187,8 +204,33 @@ export declare interface ChatEventEnvelope<T = unknown> {
     data: T;
 }
 
+export declare type ChatFileChange = {
+    id: string;
+    workspacePath: string;
+    title: string;
+    operation: 'added' | 'modified' | 'deleted' | 'unknown';
+    before?: FileRevision | null;
+    after?: FileRevision | null;
+    resource?: Extract<ChatTaskSummaryResourceReference, {
+        type: 'file_change';
+    }>;
+    coverage: 'observed' | 'legacy';
+    messageId?: string;
+    startedAt?: string;
+    updatedAt?: string;
+};
+
 export declare const CHATKIT_TASK_SUMMARY_OPEN_RESOURCE_EFFECT: "task_summary.open_resource";
 
+export declare interface ChatKitApprovalsOptions {
+    /** Existing integrations keep the composer placement by default. */
+    placement?: 'composer' | 'inline';
+    onDecision?: (input: ApprovalDecisionRequest) => Promise<{
+        accepted: boolean;
+    }>;
+    onAction?: (input: ApprovalActionRequest) => Promise<void> | void;
+}
+
 export declare type ChatKitClientSecretObject = {
     secret: string;
     organizationId?: string;
@@ -232,6 +274,7 @@ export declare interface ChatKitElementEventMap {
     }>;
     'chatkit.project.change': CustomEvent<{
         projectId: string | null;
+        selection?: ProjectSelection;
     }>;
     'chatkit.connectors.change': CustomEvent<{
         connectorBindingIds: string[];
@@ -280,6 +323,7 @@ export declare type ChatKitEvents = {
     /** Emitted when the user changes the active Xpert project in the composer. */
     'chatkit.project.change': CustomEvent<{
         projectId: string | null;
+        selection?: ProjectSelection;
     }>;
     /** Emitted when the user changes the Connector bindings selected for the conversation. */
     'chatkit.connectors.change': CustomEvent<{
@@ -488,6 +532,8 @@ export declare type ChatKitOptions = {
      * Optional animated pet companion rendered by the ChatKit web component over
      * the host page viewport.
      * Passing `true` enables the default built-in pet.
+     * Explicit `false` disables pets and local pet controls in chat mode,
+     * overriding saved user preferences. Pet display mode still requires a pet.
      *
      * @default false
      */
@@ -499,6 +545,8 @@ export declare type ChatKitOptions = {
      * @default null
      */
     initialThread?: null | string;
+    /** Generic approval placement and host decision callbacks. */
+    approvals?: ChatKitApprovalsOptions;
     /**
      * A map of handlers for the client tools configured on your server. The keys
      * are the names of the client tools, and the values are functions that
@@ -528,6 +576,8 @@ export declare type ChatKitOptions = {
      */
     header?: {
         enabled?: boolean;
+        /** Enable native Electron dragging/OS double-click behavior on unused chat and Workbench header space. Defaults to false. */
+        windowDrag?: boolean;
         /**
          * Configuration for header title display, which defaults to showing thread titles.
          */
@@ -647,6 +697,12 @@ export declare type ChatKitOptions = {
          */
         projects?: {
             enabled?: boolean;
+            /** Initial conversation intent. Binding a running conversation does not change this option. */
+            selection?: ProjectSelection;
+            /** Offer automatic creation on first send when the Assistant supports it. */
+            autoNewEnabled?: boolean;
+            /** Hide the no-Project choice for Assistants requiring a Project workspace. */
+            allowNone?: boolean;
             /**
              * Allow the user to request Project creation from the selector.
              * Defaults to true when Project selection is enabled. Set this to false
@@ -956,6 +1012,16 @@ export declare type ChatKitWorkbenchClientCommandRequest = {
     viewKey: string;
 };
 
+/** Authenticated host response consumed only by ChatKit, never forwarded to a plugin. */
+export declare type ChatKitWorkbenchNavigationSession = {
+    assistantId: string;
+    projectId: string | null;
+    threadId: string | null;
+    conversationId?: string;
+    secret: string;
+    organizationId?: string;
+};
+
 export declare type ChatKitWorkbenchOptions = {
     /** Show external Assistant executions in a native workbench tab. Enabled by default. */
     externalAssistants?: {
@@ -967,6 +1033,14 @@ export declare type ChatKitWorkbenchOptions = {
      * @default false
      */
     enabled?: boolean;
+    /**
+     * Show a vertical strip of available remote-view icons at the right edge of
+     * chat while the workbench is closed. Clicking an icon opens that view.
+     * Requires `workbench.enabled`. Disabled by default.
+     */
+    viewRail?: {
+        enabled?: boolean;
+    };
     /** Native side chat branched from the current thread. Disabled by default. */
     sideChat?: {
         enabled?: boolean;
@@ -974,6 +1048,13 @@ export declare type ChatKitWorkbenchOptions = {
     /**
      * Handles manifest-declared client commands that are not implemented by
      * ChatKit itself.
+     * For assistant.conversation/project navigation, resolve and authorize the
+     * requested resource on the server, then return
+     * `{ success: true, session: ChatKitWorkbenchNavigationSession }`.
+     * ChatKit switches its runtime scope and uses the same callback to refresh
+     * this scoped session. Credentials are stripped from the remote-view reply.
+     * Hosts that perform navigation themselves may return
+     * `{ success: true, status: 'opened' }` without a session.
      */
     onClientCommand?: (request: ChatKitWorkbenchClientCommandRequest) => unknown | Promise<unknown>;
 };
@@ -1172,6 +1253,12 @@ export declare type ChatTaskSummaryOutput = {
     resource?: ChatTaskSummaryResourceReference;
     messageId?: string;
     updatedAt?: string;
+    /** Only host-verified, explicitly presented files get message-end cards. */
+    origin?: 'tool' | 'integration' | 'legacy';
+    workspacePath?: string;
+    mimeType?: string;
+    size?: number;
+    sha256?: string;
 };
 
 export declare type ChatTaskSummaryOutputKind = 'file' | 'image' | 'document' | 'spreadsheet' | 'presentation' | 'site' | 'url' | 'mcp_app';
@@ -1196,7 +1283,8 @@ export declare type ChatTaskSummaryResourceReference = {
 } | {
     type: 'artifact';
     artifactId: string;
-} | {
+    artifactVersionId?: string;
+} | FileChangeResource | FileChangeSetResource | {
     type: 'browser';
     serviceId?: string;
     url?: string;
@@ -1287,6 +1375,9 @@ declare type ControlSize = '3xs' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2
 
 declare type ControlVariant = 'solid' | 'soft' | 'outline' | 'ghost';
 
+/** Exact line LCS with bounded CPU/memory. Unknown text never becomes zero changes. */
+export declare function countFileChangeLines(report: FileChangeReport): FileChangeLineStats;
+
 declare type CustomApiConfig = {
     /**
      * The URL (relative or absolute) of the ChatKit API. The configured endpoint
@@ -1394,6 +1485,85 @@ export declare type Entity = {
 
 export declare type EventHandler<K extends keyof ChatKitEvents> = (event: ChatKitEvents[K]) => any;
 
+export declare type FileActivityMessage = {
+    id?: string;
+    content?: unknown;
+    taskSummary?: TChatTaskSummaryContribution;
+    updatedAt?: string | Date;
+    createdAt?: string | Date;
+};
+
+/** Host-owned facts from a tool execution, never an additional tool invocation. */
+export declare type FileActivityReceipt = {
+    version: 1;
+    receiptId: string;
+    toolCallId: string;
+    updatedAt: string;
+} & ({
+    kind: 'changes';
+    coverage: 'bounded' | 'partial' | 'unavailable';
+    fileChanges: ChatFileChange[];
+} | {
+    kind: 'delivery';
+    status: 'success';
+    outputs: ChatTaskSummaryOutput[];
+} | {
+    kind: 'delivery';
+    status: 'error';
+    error: string;
+});
+
+export declare type FileChangeLineStats = {
+    status: 'ready';
+    added: number;
+    removed: number;
+} | {
+    status: 'unavailable';
+};
+
+/** Stable cache identity for a fixed review range; never identifies mutable workspace bytes. */
+export declare function fileChangeRangeKey(resource: Extract<ChatTaskSummaryResourceReference, {
+    type: 'file_change';
+}>): string;
+
+/** Private review payload. Never include text/diffs in compact task summaries. */
+export declare type FileChangeReport = {
+    schema: 'xpert.file-change.v1';
+    workspacePath: string;
+    before: (FileRevision & {
+        text?: string;
+    }) | null;
+    after: (FileRevision & {
+        text?: string;
+    }) | null;
+};
+
+export declare type FileChangeResource = {
+    type: 'file_change';
+    first: {
+        artifactId: string;
+        artifactVersionId: string;
+    };
+    last: {
+        artifactId: string;
+        artifactVersionId: string;
+    };
+};
+
+export declare type FileChangeSetResource = {
+    type: 'file_change_set';
+    messageId: string;
+    changes: {
+        workspacePath: string;
+        resource?: FileChangeResource;
+    }[];
+};
+
+export declare type FileRevision = {
+    sha256: string;
+    size: number;
+};
+
 export declare type FileUploadStrategy = {
     type: 'two_phase';
 } | {
@@ -1420,6 +1590,11 @@ export declare type Form = {
     direction?: 'row' | 'col';
 } & BoxBaseProps;
 
+export declare function getFileActivityContribution(value: unknown): TChatTaskSummaryContribution | null;
+
+/** Compatibility uses explicit metadata and the original call identity, never labels or ID suffixes. */
+export declare function getLegacyFileActivityContribution(value: unknown): TChatTaskSummaryContribution | null;
+
 /** Works for both streamed tool components and persisted message summaries. */
 export declare function getMessageSkillUsages(message: {
     content?: unknown;
@@ -1486,6 +1661,8 @@ export declare interface HITLRejectDecision {
 }
 
 export declare interface HITLRequest {
+    host?: ApprovalHostReference;
+    toolCallId?: string;
     actionRequests: HITLActionRequest[];
     reviewConfigs: HITLReviewConfig[];
     elicitation?: HITLMCPElicitation;
@@ -1662,6 +1839,8 @@ export declare interface InterruptPayload extends LangGraphInterruptPayload<Inte
 
 export declare type InterruptRequest = ToolCallRequest | ClientToolRequest | HITLRequest;
 
+export declare function isApprovalHostReference(value: unknown): value is ApprovalHostReference;
+
 export declare function isClientToolInterrupt(value: unknown): value is ClientToolInterrupt;
 
 export declare function isClientToolInterruptPayload(value: unknown): value is ClientToolInterruptPayload;
@@ -1670,6 +1849,8 @@ export declare function isClientToolInterruptTask(value: unknown): value is Clie
 
 export declare function isClientToolRequest(value: unknown): value is ClientToolRequest;
 
+export declare function isFileActivityContent(value: unknown): boolean;
+
 export declare function isHITLDecisionType(value: unknown): value is HITLDecisionType;
 
 export declare function isHITLInterrupt(value: unknown): value is HITLInterrupt;
@@ -1764,6 +1945,9 @@ export declare type Markdown = {
 /** Merge only observations belonging to the same message. Keep the first read. */
 export declare function mergeChatSkillUsages(...groups: ReadonlyArray<readonly ChatSkillUsage[] | undefined>): ChatSkillUsage[];
 
+/** Collapse observed operations to the net change, retaining immutable first/last review references. */
+export declare function mergeFileChanges(items: ChatFileChange[]): ChatFileChange[];
+
 export declare function mergePetSpriteAtlas(override?: ChatKitPetSpriteAtlas): PetSpriteAtlasDefinition;
 
 export declare type MessageContentImageUrl = {
@@ -1779,6 +1963,17 @@ export declare type MessageContentText = {
     text: string;
 };
 
+export declare type MessageFileChangeStats = {
+    messageId: string;
+    items: {
+        workspacePath: string;
+        resource?: Extract<ChatTaskSummaryResourceReference, {
+            type: 'file_change';
+        }>;
+        stats: FileChangeLineStats;
+    }[];
+};
+
 export declare type ModelOption = {
     /** Identifier used when submitting a message. */
     id: string;
@@ -1812,6 +2007,10 @@ export declare type NormalizedPetOptions = {
     imageRendering: NonNullable<ChatKitPetOptions['imageRendering']>;
 };
 
+export declare function normalizeFileChanges(value: unknown): ChatFileChange[];
+
+export declare function normalizeFileOutputs(value: unknown): ChatTaskSummaryOutput[];
+
 export declare function normalizeHITLRequest(value: unknown): HITLRequest | null;
 
 export declare function normalizePetOptions(pet: ChatKitOptions['pet'] | null): NormalizedPetOptions | null;
@@ -1820,6 +2019,10 @@ export declare function normalizeRequestLanguage(locale?: string | null): string
 
 export declare function normalizeThreadReference(value: unknown): ChatKitThreadReference | null;
 
+export declare function parseFileActivityContent(value: unknown): TMessageContentFileActivity | null;
+
+export declare function parseFileChangeReport(value: unknown): FileChangeReport | null;
+
 export declare const PET_ANIMATION_NAMES: readonly ["idle", "running-right", "running-left", "waving", "jumping", "failed", "waiting", "running", "review"];
 
 export declare type PetFrameAnimationDefinition = {
@@ -1905,6 +2108,19 @@ export declare type PetViewport = {
     height: number;
 };
 
+/** Shared live/history projection. Proven tool writes move out of outputs, never filename-based classification. */
+export declare function projectMessageFileActivity(message: FileActivityMessage, contribution: TChatTaskSummaryContribution): TChatTaskSummaryContribution;
+
+/** Explicit user intent for the next conversation; absence retains legacy host behavior. */
+export declare type ProjectSelection = {
+    mode: 'auto-new';
+} | {
+    mode: 'none';
+} | {
+    mode: 'existing';
+    projectId: string;
+};
+
 export declare type RadioGroup = {
     type: 'RadioGroup';
     key?: string;
@@ -2154,6 +2370,7 @@ export declare type TChatRequest = {
     state?: TXpertChatState;
     agentKey?: string;
     projectId?: string;
+    projectSelection?: ProjectSelection;
     conversationId?: string;
     environmentId?: string;
     id?: string;
@@ -2202,6 +2419,11 @@ export declare type TChatTaskSummaryContribution = {
     outputs?: ChatTaskSummaryOutput[];
     sources?: ChatTaskSummarySource[];
     skillUsages?: ChatSkillUsage[];
+    /** Presence marks the new semantic projection; old writes are never deliveries. */
+    fileActivityVersion?: 1;
+    fileActivityToolCallId?: string;
+    fileChangeCoverage?: 'bounded' | 'partial' | 'unavailable';
+    fileChanges?: ChatFileChange[];
 };
 
 /**
@@ -2505,7 +2727,7 @@ export declare type TMessageContent = string | TMessageContentComplex[];
 /**
  * Enhance {@link MessageContentComplex} in Langchain.js
  */
-export declare type TMessageContentComplex = (TMessageContentText | TMessageContentReasoning | MessageContentImageUrl | TMessageContentComponent | TMessageContentMemory | (Record<string, any> & {
+export declare type TMessageContentComplex = (TMessageContentText | TMessageContentReasoning | MessageContentImageUrl | TMessageContentComponent | TMessageContentFileActivity | TMessageContentMemory | (Record<string, any> & {
     type?: 'text' | 'image_url' | string;
 }) | (Record<string, any> & {
     type?: never;
@@ -2533,6 +2755,17 @@ export declare type TMessageContentComponent<T extends object = object> = {
     runId?: string;
 };
 
+export declare type TMessageContentFileActivity = {
+    id: string;
+    type: 'file_activity';
+    data: FileActivityReceipt;
+    messageId?: string;
+    executionId?: string;
+    agentKey?: string;
+    parentExecutionId?: string;
+    runId?: string;
+};
+
 /**
  * MCP App component item in a LangChain-compatible complex message content
  * array.
@@ -2756,6 +2989,9 @@ export declare type TXpertChatTarget = {
     executionId?: string;
 };
 
+/** Receipts are immutable terminal facts; replay replaces by identity, never appends a second operation. */
+export declare function upsertFileActivityContent<T>(content: T[], receipt: TMessageContentFileActivity): (T | TMessageContentFileActivity)[];
+
 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;