@xpert-ai/chatkit-types 0.6.1 → 0.6.3

package/dist/index.d.ts

@@ -187,6 +187,22 @@ 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 type ChatKitClientSecretObject = {
@@ -388,6 +404,7 @@ export declare type ChatKitMcpAppsOptions = {
 };
 
 export declare interface ChatkitMessage {
+    taskSummary?: TChatTaskSummaryContribution;
     createdAt?: string | Date | null;
     updatedAt?: string | Date | null;
     historical?: boolean;
@@ -793,7 +810,7 @@ export declare type ChatKitQuoteReference = ChatKitReferenceBase & {
     source?: string;
 };
 
-export declare type ChatKitReference = ChatKitCodeReference | ChatKitQuoteReference | ChatKitImageReference | ChatKitElementReference | ChatKitFileElementReference;
+export declare type ChatKitReference = ChatKitThreadReference | ChatKitCodeReference | ChatKitQuoteReference | ChatKitImageReference | ChatKitElementReference | ChatKitFileElementReference;
 
 export declare type ChatKitReferenceBase = {
     id?: string;
@@ -938,6 +955,15 @@ export declare type ChatKitTheme = {
     };
 };
 
+/** A live reference to a conversation branch, never a client-supplied transcript. */
+export declare type ChatKitThreadReference = {
+    type: 'thread';
+    id?: string;
+    label?: string;
+    conversationId: string;
+    threadId: string;
+};
+
 export declare type ChatKitWorkbenchClientCommandRequest = {
     commandKey: string;
     payload?: unknown;
@@ -1129,6 +1155,23 @@ export declare type ChatRequestStorageFileHandle = ChatRequestFileBase & {
     storageProvider?: string;
 };
 
+/** Snapshot produced by the runtime after successfully loading skill instructions. */
+export declare type ChatSkillUsage = {
+    skillId: string;
+    name: string;
+    version: string;
+    source: {
+        type: 'workspace' | 'project' | 'assistant' | 'plugin';
+        id: string;
+    };
+    activation: 'read';
+    toolCallId: string;
+    executionId?: string;
+    loadedAt: string;
+};
+
+export declare function chatSkillUsageKey(usage: ChatSkillUsage): string;
+
 export declare type ChatTaskSummaryOpenResourceEffect = {
     resource: ChatTaskSummaryResourceReference;
     conversationId?: string;
@@ -1145,6 +1188,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';
@@ -1169,7 +1218,8 @@ export declare type ChatTaskSummaryResourceReference = {
 } | {
     type: 'artifact';
     artifactId: string;
-} | {
+    artifactVersionId?: string;
+} | FileChangeResource | FileChangeSetResource | {
     type: 'browser';
     serviceId?: string;
     url?: string;
@@ -1260,6 +1310,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
@@ -1367,6 +1420,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';
 } | {
@@ -1393,6 +1525,17 @@ 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;
+    taskSummary?: unknown;
+}): ChatSkillUsage[];
+
 export declare function getPinnedPetPosition(pin: ChatKitPetPin, size: PetSize, viewport: PetViewport, padding: ChatKitPetBoundsPadding): PetPosition;
 
 export declare type GrayscaleOptions = {
@@ -1637,6 +1780,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;
@@ -1728,6 +1873,12 @@ export declare type Markdown = {
     streaming?: boolean;
 };
 
+/** 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 = {
@@ -1743,6 +1894,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;
@@ -1765,6 +1927,9 @@ export declare type ModelOption = {
 
 export declare function normalizeBoundsPadding(value?: number | Partial<ChatKitPetBoundsPadding>): ChatKitPetBoundsPadding;
 
+/** JSON boundary: allowlist fields rather than forwarding paths or raw tool data. */
+export declare function normalizeChatSkillUsages(value: unknown): ChatSkillUsage[];
+
 export declare type NormalizedPetOptions = {
     character: ChatKitPetCharacter;
     position: Required<Pick<NonNullable<ChatKitPetOptions['position']>, 'draggable' | 'persist' | 'scale' | 'zIndex'>> & Pick<NonNullable<ChatKitPetOptions['position']>, 'pin' | 'boundsPadding'>;
@@ -1773,12 +1938,22 @@ 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;
 
 export declare function normalizeRequestLanguage(locale?: string | null): string | undefined;
 
+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 = {
@@ -1864,6 +2039,9 @@ 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;
+
 export declare type RadioGroup = {
     type: 'RadioGroup';
     key?: string;
@@ -2160,6 +2338,12 @@ export declare type TChatTaskSummaryContribution = {
     todos?: ChatTaskSummaryTodos;
     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[];
 };
 
 /**
@@ -2463,7 +2647,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;
@@ -2491,6 +2675,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.
@@ -2714,6 +2909,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;