byterover-cli 0.4.1 → 1.0.0

package/dist/core/interfaces/cipher/message-factory.js

@@ -0,0 +1,252 @@
+/**
+ * Factory functions for creating validated message parts and messages.
+ *
+ * These factories provide a consistent way to create message parts with:
+ * - Proper type assignment
+ * - Optional metadata and synthetic flags
+ * - Default values where appropriate
+ *
+ */
+// ==================== TEXT PART FACTORY ====================
+/**
+ * Create a TextPart with the given text content.
+ */
+export function createTextPart(text, options) {
+    return {
+        text,
+        type: 'text',
+        ...(options?.synthetic !== undefined && { synthetic: options.synthetic }),
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+// ==================== IMAGE PART FACTORY ====================
+/**
+ * Create an ImagePart with the given image data.
+ */
+export function createImagePart(image, mimeType, options) {
+    return {
+        image,
+        type: 'image',
+        ...(mimeType && { mimeType }),
+        ...(options?.synthetic !== undefined && { synthetic: options.synthetic }),
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+// ==================== FILE PART FACTORY ====================
+/**
+ * Create a FilePart with the given file data.
+ */
+export function createFilePart(data, mimeType, filename, options) {
+    return {
+        data,
+        mimeType,
+        type: 'file',
+        ...(filename && { filename }),
+        ...(options?.synthetic !== undefined && { synthetic: options.synthetic }),
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+// ==================== REASONING PART FACTORY ====================
+/**
+ * Create a ReasoningPart with the given thinking text.
+ */
+export function createReasoningPart(text, summary, options) {
+    return {
+        text,
+        type: 'reasoning',
+        ...(summary && { summary }),
+        ...(options?.synthetic !== undefined && { synthetic: options.synthetic }),
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+// ==================== TOOL PART FACTORY ====================
+/**
+ * Create a ToolPart in pending state.
+ */
+export function createToolPart(callId, toolName, input, options) {
+    const state = {
+        input,
+        status: 'pending',
+    };
+    return {
+        callId,
+        state,
+        toolName,
+        type: 'tool',
+        ...(options?.synthetic !== undefined && { synthetic: options.synthetic }),
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+/**
+ * Create a ToolPart in running state.
+ */
+export function createRunningToolPart(callId, toolName, input, options) {
+    const state = {
+        input,
+        startedAt: options?.startedAt ?? Date.now(),
+        status: 'running',
+    };
+    return {
+        callId,
+        state,
+        toolName,
+        type: 'tool',
+        ...(options?.synthetic !== undefined && { synthetic: options.synthetic }),
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+/**
+ * Create a ToolPart in completed state.
+ */
+export function createCompletedToolPart(options) {
+    const time = options.time ?? { end: Date.now(), start: Date.now() };
+    const state = {
+        input: options.input,
+        output: options.output,
+        status: 'completed',
+        time,
+        ...(options.additionalOptions?.attachments && { attachments: options.additionalOptions.attachments }),
+        ...(options.additionalOptions?.compactedAt && { compactedAt: options.additionalOptions.compactedAt }),
+        ...(options.additionalOptions?.metadata && { metadata: options.additionalOptions.metadata }),
+        ...(options.additionalOptions?.title && { title: options.additionalOptions.title }),
+    };
+    return {
+        callId: options.callId,
+        state,
+        toolName: options.toolName,
+        type: 'tool',
+        ...(options.synthetic !== undefined && { synthetic: options.synthetic }),
+        ...(options.metadata && { metadata: options.metadata }),
+    };
+}
+/**
+ * Create a ToolPart in error state.
+ */
+export function createErrorToolPart(options) {
+    const time = options.time ?? { end: Date.now(), start: Date.now() };
+    const state = {
+        error: options.error,
+        input: options.input,
+        status: 'error',
+        time,
+    };
+    return {
+        callId: options.callId,
+        state,
+        toolName: options.toolName,
+        type: 'tool',
+        ...(options.synthetic !== undefined && { synthetic: options.synthetic }),
+        ...(options.metadata && { metadata: options.metadata }),
+    };
+}
+// ==================== TOOL STATE TRANSITIONS ====================
+/**
+ * Transition a tool state from pending to running.
+ */
+export function transitionToRunning(state, startedAt = Date.now()) {
+    return {
+        input: state.input,
+        startedAt,
+        status: 'running',
+    };
+}
+/**
+ * Transition a tool state from running to completed.
+ */
+export function transitionToCompleted(state, output, endedAt = Date.now(), additionalOptions) {
+    return {
+        input: state.input,
+        output,
+        status: 'completed',
+        time: { end: endedAt, start: state.startedAt },
+        ...(additionalOptions?.attachments && { attachments: additionalOptions.attachments }),
+        ...(additionalOptions?.metadata && { metadata: additionalOptions.metadata }),
+        ...(additionalOptions?.title && { title: additionalOptions.title }),
+    };
+}
+/**
+ * Transition a tool state from running to error.
+ */
+export function transitionToError(state, error, endedAt = Date.now()) {
+    return {
+        error,
+        input: state.input,
+        status: 'error',
+        time: { end: endedAt, start: state.startedAt },
+    };
+}
+// ==================== TOOL CALL FACTORY ====================
+/**
+ * Create a ToolCall from function name and arguments.
+ */
+export function createToolCall(id, name, args) {
+    return {
+        function: {
+            arguments: typeof args === 'string' ? args : JSON.stringify(args),
+            name,
+        },
+        id,
+        type: 'function',
+    };
+}
+/**
+ * Create a system message.
+ */
+export function createSystemMessage(content, options) {
+    return {
+        content,
+        role: 'system',
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+/**
+ * Create a user message with text content.
+ */
+export function createUserMessage(content, options) {
+    return {
+        content: typeof content === 'string' ? content : content,
+        role: 'user',
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+/**
+ * Create an assistant message with text content.
+ */
+export function createAssistantMessage(content, additionalOptions, options) {
+    return {
+        content,
+        role: 'assistant',
+        ...(additionalOptions?.reasoning && { reasoning: additionalOptions.reasoning }),
+        ...(additionalOptions?.thought && { thought: additionalOptions.thought }),
+        ...(additionalOptions?.thoughtSummary && { thoughtSummary: additionalOptions.thoughtSummary }),
+        ...(additionalOptions?.toolCalls && { toolCalls: additionalOptions.toolCalls }),
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+/**
+ * Create a tool result message.
+ */
+export function createToolResultMessage(content, toolCallId, name, options) {
+    return {
+        content,
+        name,
+        role: 'tool',
+        toolCallId,
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+/**
+ * Create a summary message (used by compression strategies).
+ */
+export function createSummaryMessage(summaryContent, summarizedMessageCount, options) {
+    return {
+        content: `[Conversation Summary]\n${summaryContent}`,
+        metadata: {
+            compactedAt: Date.now(),
+            isSummary: true,
+            summarizedMessageCount,
+            ...options?.additionalMetadata,
+        },
+        role: 'system',
+    };
+}

package/dist/core/interfaces/cipher/message-type-guards.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Type guards for discriminated union types in the message system.
+ *
+ * These guards provide runtime type narrowing for:
+ * - MessagePart union (text, image, file, reasoning, tool)
+ * - ToolState union (pending, running, completed, error)
+ * - InternalMessage roles (system, user, assistant, tool)
+ *
+ */
+import type { FilePart, ImagePart, InternalMessage, MessagePart, ReasoningPart, TextPart, ToolPart, ToolState, ToolStateCompleted, ToolStateError, ToolStatePending, ToolStateRunning } from './message-types.js';
+/**
+ * Check if a message part is a TextPart.
+ */
+export declare function isTextPart(part: MessagePart): part is TextPart;
+/**
+ * Check if a message part is an ImagePart.
+ */
+export declare function isImagePart(part: MessagePart): part is ImagePart;
+/**
+ * Check if a message part is a FilePart.
+ */
+export declare function isFilePart(part: MessagePart): part is FilePart;
+/**
+ * Check if a message part is a ReasoningPart.
+ */
+export declare function isReasoningPart(part: MessagePart): part is ReasoningPart;
+/**
+ * Check if a message part is a ToolPart.
+ */
+export declare function isToolPart(part: MessagePart): part is ToolPart;
+/**
+ * Check if a tool state is pending.
+ */
+export declare function isToolPending(state: ToolState): state is ToolStatePending;
+/**
+ * Check if a tool state is running.
+ */
+export declare function isToolRunning(state: ToolState): state is ToolStateRunning;
+/**
+ * Check if a tool state is completed.
+ */
+export declare function isToolCompleted(state: ToolState): state is ToolStateCompleted;
+/**
+ * Check if a tool state is error.
+ */
+export declare function isToolError(state: ToolState): state is ToolStateError;
+/**
+ * Type for system messages.
+ */
+export type SystemMessage = InternalMessage & {
+    role: 'system';
+};
+/**
+ * Type for user messages.
+ */
+export type UserMessage = InternalMessage & {
+    role: 'user';
+};
+/**
+ * Type for assistant messages.
+ */
+export type AssistantMessage = InternalMessage & {
+    role: 'assistant';
+};
+/**
+ * Type for tool messages.
+ */
+export type ToolMessage = InternalMessage & {
+    role: 'tool';
+};
+/**
+ * Check if a message is a system message.
+ */
+export declare function isSystemMessage(msg: InternalMessage): msg is SystemMessage;
+/**
+ * Check if a message is a user message.
+ */
+export declare function isUserMessage(msg: InternalMessage): msg is UserMessage;
+/**
+ * Check if a message is an assistant message.
+ */
+export declare function isAssistantMessage(msg: InternalMessage): msg is AssistantMessage;
+/**
+ * Check if a message is a tool message.
+ */
+export declare function isToolMessage(msg: InternalMessage): msg is ToolMessage;
+/**
+ * Check if message content is a string.
+ */
+export declare function isStringContent(content: InternalMessage['content']): content is string;
+/**
+ * Check if message content is an array of parts.
+ */
+export declare function isPartsContent(content: InternalMessage['content']): content is MessagePart[];
+/**
+ * Check if message content is null (e.g., assistant message with only tool calls).
+ */
+export declare function isNullContent(content: InternalMessage['content']): content is null;
+/**
+ * Extract text content from a message part array.
+ * Returns concatenated text from all TextParts.
+ */
+export declare function extractTextFromParts(parts: MessagePart[]): string;
+/**
+ * Extract all images from a message part array.
+ */
+export declare function extractImagesFromParts(parts: MessagePart[]): ImagePart[];
+/**
+ * Extract all files from a message part array.
+ */
+export declare function extractFilesFromParts(parts: MessagePart[]): FilePart[];
+/**
+ * Extract all tool parts from a message part array.
+ */
+export declare function extractToolPartsFromParts(parts: MessagePart[]): ToolPart[];
+/**
+ * Check if a message has any attachments (images or files).
+ */
+export declare function hasAttachments(parts: MessagePart[]): boolean;
+/**
+ * Check if a message has any tool calls.
+ */
+export declare function hasToolCalls(msg: InternalMessage): boolean;
+/**
+ * Get completed tool parts from a message part array.
+ */
+export declare function getCompletedToolParts(parts: MessagePart[]): ToolPart[];
+/**
+ * Get error tool parts from a message part array.
+ */
+export declare function getErrorToolParts(parts: MessagePart[]): ToolPart[];
+/**
+ * Get running tool parts from a message part array.
+ */
+export declare function getRunningToolParts(parts: MessagePart[]): ToolPart[];
+/**
+ * Get pending tool parts from a message part array.
+ */
+export declare function getPendingToolParts(parts: MessagePart[]): ToolPart[];

package/dist/core/interfaces/cipher/message-type-guards.js

@@ -0,0 +1,173 @@
+/**
+ * Type guards for discriminated union types in the message system.
+ *
+ * These guards provide runtime type narrowing for:
+ * - MessagePart union (text, image, file, reasoning, tool)
+ * - ToolState union (pending, running, completed, error)
+ * - InternalMessage roles (system, user, assistant, tool)
+ *
+ */
+// ==================== MESSAGE PART TYPE GUARDS ====================
+/**
+ * Check if a message part is a TextPart.
+ */
+export function isTextPart(part) {
+    return part.type === 'text';
+}
+/**
+ * Check if a message part is an ImagePart.
+ */
+export function isImagePart(part) {
+    return part.type === 'image';
+}
+/**
+ * Check if a message part is a FilePart.
+ */
+export function isFilePart(part) {
+    return part.type === 'file';
+}
+/**
+ * Check if a message part is a ReasoningPart.
+ */
+export function isReasoningPart(part) {
+    return part.type === 'reasoning';
+}
+/**
+ * Check if a message part is a ToolPart.
+ */
+export function isToolPart(part) {
+    return part.type === 'tool';
+}
+// ==================== TOOL STATE TYPE GUARDS ====================
+/**
+ * Check if a tool state is pending.
+ */
+export function isToolPending(state) {
+    return state.status === 'pending';
+}
+/**
+ * Check if a tool state is running.
+ */
+export function isToolRunning(state) {
+    return state.status === 'running';
+}
+/**
+ * Check if a tool state is completed.
+ */
+export function isToolCompleted(state) {
+    return state.status === 'completed';
+}
+/**
+ * Check if a tool state is error.
+ */
+export function isToolError(state) {
+    return state.status === 'error';
+}
+/**
+ * Check if a message is a system message.
+ */
+export function isSystemMessage(msg) {
+    return msg.role === 'system';
+}
+/**
+ * Check if a message is a user message.
+ */
+export function isUserMessage(msg) {
+    return msg.role === 'user';
+}
+/**
+ * Check if a message is an assistant message.
+ */
+export function isAssistantMessage(msg) {
+    return msg.role === 'assistant';
+}
+/**
+ * Check if a message is a tool message.
+ */
+export function isToolMessage(msg) {
+    return msg.role === 'tool';
+}
+// ==================== CONTENT TYPE GUARDS ====================
+/**
+ * Check if message content is a string.
+ */
+export function isStringContent(content) {
+    return typeof content === 'string';
+}
+/**
+ * Check if message content is an array of parts.
+ */
+export function isPartsContent(content) {
+    return Array.isArray(content);
+}
+/**
+ * Check if message content is null (e.g., assistant message with only tool calls).
+ */
+export function isNullContent(content) {
+    return content === null;
+}
+// ==================== UTILITY FUNCTIONS ====================
+/**
+ * Extract text content from a message part array.
+ * Returns concatenated text from all TextParts.
+ */
+export function extractTextFromParts(parts) {
+    return parts
+        .filter((p) => isTextPart(p))
+        .map((p) => p.text)
+        .join('\n');
+}
+/**
+ * Extract all images from a message part array.
+ */
+export function extractImagesFromParts(parts) {
+    return parts.filter((p) => isImagePart(p));
+}
+/**
+ * Extract all files from a message part array.
+ */
+export function extractFilesFromParts(parts) {
+    return parts.filter((p) => isFilePart(p));
+}
+/**
+ * Extract all tool parts from a message part array.
+ */
+export function extractToolPartsFromParts(parts) {
+    return parts.filter((p) => isToolPart(p));
+}
+/**
+ * Check if a message has any attachments (images or files).
+ */
+export function hasAttachments(parts) {
+    return parts.some((p) => isImagePart(p) || isFilePart(p));
+}
+/**
+ * Check if a message has any tool calls.
+ */
+export function hasToolCalls(msg) {
+    return Array.isArray(msg.toolCalls) && msg.toolCalls.length > 0;
+}
+/**
+ * Get completed tool parts from a message part array.
+ */
+export function getCompletedToolParts(parts) {
+    return parts.filter((p) => isToolPart(p) && isToolCompleted(p.state));
+}
+/**
+ * Get error tool parts from a message part array.
+ */
+export function getErrorToolParts(parts) {
+    return parts.filter((p) => isToolPart(p) && isToolError(p.state));
+}
+/**
+ * Get running tool parts from a message part array.
+ */
+export function getRunningToolParts(parts) {
+    return parts.filter((p) => isToolPart(p) && isToolRunning(p.state));
+}
+/**
+ * Get pending tool parts from a message part array.
+ */
+export function getPendingToolParts(parts) {
+    return parts.filter((p) => isToolPart(p) && isToolPending(p.state));
+}