byterover-cli 1.0.4 → 1.0.5

package/dist/core/domain/transport/schemas.js

@@ -249,6 +249,8 @@ export const TransportLlmEventList = [
 export const TransportAgentEventNames = {
     CONNECTED: 'agent:connected',
     DISCONNECTED: 'agent:disconnected',
+    NEW_SESSION: 'agent:newSession',
+    NEW_SESSION_CREATED: 'agent:newSessionCreated',
     REGISTER: 'agent:register',
     RESTART: 'agent:restart',
     RESTARTED: 'agent:restarted',
@@ -272,10 +274,10 @@ export const TransportSessionEventNames = {
  * Internal message, not exposed to external clients
  */
 export const TaskExecuteSchema = z.object({
-    /** Client ID that created the task (for response routing) */
-    clientId: z.string(),
     /** Client's working directory for file validation */
     clientCwd: z.string().optional(),
+    /** Client ID that created the task (for response routing) */
+    clientId: z.string(),
     /** Task content/prompt */
     content: z.string(),
     /** Optional file paths for curate --files */
@@ -560,3 +562,22 @@ export const AgentRestartResponseSchema = z.object({
     /** Whether the restart was initiated successfully */
     success: z.boolean(),
 });
+/**
+ * Request to create a new session (end current, start fresh).
+ * Used by /new command to start a fresh conversation.
+ */
+export const AgentNewSessionRequestSchema = z.object({
+    /** Optional reason for new session (for logging) */
+    reason: z.string().optional(),
+});
+/**
+ * Response after new session is created.
+ */
+export const AgentNewSessionResponseSchema = z.object({
+    /** Error message if session creation failed */
+    error: z.string().optional(),
+    /** The new session ID */
+    sessionId: z.string().optional(),
+    /** Whether the new session was created successfully */
+    success: z.boolean(),
+});

package/dist/core/interfaces/cipher/i-session-persistence.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Interface for Session Persistence Operations
+ *
+ * Defines the contract for session metadata storage and retrieval.
+ * Implementation uses JSON files in .brv/sessions/ directory.
+ */
+import type { ActiveSessionPointer, SessionInfo, SessionMetadata } from '../../domain/cipher/session/session-metadata.js';
+/**
+ * Session retention configuration for auto-cleanup.
+ */
+export interface SessionRetentionConfig {
+    /** Maximum age in days before auto-cleanup */
+    maxAgeDays: number;
+    /** Maximum number of sessions to keep */
+    maxCount: number;
+    /** Whether to run cleanup on startup */
+    runOnStartup: boolean;
+}
+/**
+ * Result of session cleanup operation.
+ */
+export interface SessionCleanupResult {
+    /** Number of corrupted session files removed */
+    corruptedRemoved: number;
+    /** Number of sessions deleted due to age */
+    deletedByAge: number;
+    /** Number of sessions deleted due to count limit */
+    deletedByCount: number;
+    /** Total sessions remaining after cleanup */
+    remaining: number;
+}
+/**
+ * Interface for session metadata persistence.
+ *
+ * Manages session metadata stored in .brv/sessions/ directory:
+ * - active.json: Current active session pointer
+ * - session-*.json: Individual session metadata files
+ */
+export interface ISessionPersistence {
+    /**
+     * Clean up expired sessions based on retention policy.
+     *
+     * @param config - Retention configuration
+     * @returns Cleanup result with counts
+     */
+    cleanupSessions(config: SessionRetentionConfig): Promise<SessionCleanupResult>;
+    /**
+     * Clear the active session pointer.
+     * Removes .brv/sessions/active.json
+     */
+    clearActiveSession(): Promise<void>;
+    /**
+     * Delete a session and its metadata.
+     *
+     * @param sessionId - Session ID to delete
+     * @returns True if session was deleted, false if not found
+     */
+    deleteSession(sessionId: string): Promise<boolean>;
+    /**
+     * Get the currently active session pointer.
+     *
+     * @returns Active session pointer or null if no active session
+     */
+    getActiveSession(): Promise<ActiveSessionPointer | null>;
+    /**
+     * Get session metadata by ID.
+     *
+     * @param sessionId - Session ID to look up
+     * @returns Session metadata or null if not found
+     */
+    getSession(sessionId: string): Promise<null | SessionMetadata>;
+    /**
+     * Check if the active session pointer is stale (process not running).
+     *
+     * @returns True if active session exists but process is not running
+     */
+    isActiveSessionStale(): Promise<boolean>;
+    /**
+     * Validate that a session belongs to the current working directory.
+     *
+     * @param sessionId - Session ID to validate
+     * @returns True if session belongs to current project
+     */
+    isSessionForCurrentProject(sessionId: string): Promise<boolean>;
+    /**
+     * List all session metadata files.
+     *
+     * @returns Array of session info sorted by lastUpdated (newest first)
+     */
+    listSessions(): Promise<SessionInfo[]>;
+    /**
+     * Mark a session as ended.
+     * Updates the session status to 'ended' and lastUpdated timestamp.
+     *
+     * @param sessionId - Session ID to mark as ended
+     */
+    markSessionEnded(sessionId: string): Promise<void>;
+    /**
+     * Mark a session as interrupted (e.g., process crashed).
+     * Updates the session status to 'interrupted'.
+     *
+     * @param sessionId - Session ID to mark as interrupted
+     */
+    markSessionInterrupted(sessionId: string): Promise<void>;
+    /**
+     * Save session metadata to disk.
+     * Creates or updates the session metadata file.
+     *
+     * @param metadata - Session metadata to save
+     */
+    saveSession(metadata: SessionMetadata): Promise<void>;
+    /**
+     * Set the active session pointer.
+     * Creates or updates .brv/sessions/active.json
+     *
+     * @param sessionId - Session ID to set as active
+     */
+    setActiveSession(sessionId: string): Promise<void>;
+    /**
+     * Set session title from first user message.
+     *
+     * @param sessionId - Session ID to update
+     * @param title - Session title
+     */
+    setSessionTitle(sessionId: string, title: string): Promise<void>;
+    /**
+     * Update session activity (lastUpdated timestamp and message count).
+     *
+     * @param sessionId - Session ID to update
+     * @param messageCount - Current message count
+     */
+    updateSessionActivity(sessionId: string, messageCount: number): Promise<void>;
+}

package/dist/core/interfaces/cipher/i-session-persistence.js

@@ -0,0 +1,7 @@
+/**
+ * Interface for Session Persistence Operations
+ *
+ * Defines the contract for session metadata storage and retrieval.
+ * Implementation uses JSON files in .brv/sessions/ directory.
+ */
+export {};

package/dist/core/interfaces/cipher/message-types.d.ts

@@ -302,6 +302,12 @@ export interface ToolCall {
      * Unique identifier for this tool call
      */
     id: string;
+    /**
+     * Thought signature for Gemini 3+ models.
+     * Required by Gemini 3 preview models to validate function calls.
+     * Uses 'skip_thought_signature_validator' as synthetic signature.
+     */
+    thoughtSignature?: string;
     /**
      * The type of tool call (currently only 'function' is supported)
      */

package/dist/core/interfaces/executor/i-curate-executor.d.ts

@@ -4,10 +4,10 @@ import type { ICipherAgent } from '../cipher/i-cipher-agent.js';
  * Agent uses its default session (Single-Session pattern).
  */
 export interface CurateExecuteOptions {
-    /** Context content to curate */
-    content: string;
     /** Client's working directory for file validation (defaults to process.cwd() if not provided) */
     clientCwd?: string;
+    /** Context content to curate */
+    content: string;
     /** Optional file paths for --files flag */
     files?: string[];
     /** Task ID for event routing (required for concurrent task isolation) */

package/dist/core/interfaces/i-context-file-reader.d.ts

@@ -1,11 +1,14 @@
+import type { Narrative, RawConcept } from '../domain/knowledge/markdown-writer.js';
 /**
  * Represents the content of a context file with extracted metadata.
  */
 export type ContextFileContent = {
     /** The raw content of the file */
     content: string;
+    narrative?: Narrative;
     /** Relative path within the context tree (e.g., "structure/context.md") */
     path: string;
+    rawConcept?: RawConcept;
     /** Title extracted from the first heading, or the relative path if no heading found */
     title: string;
 };

package/dist/core/interfaces/usecase/{i-clear-use-case.d.ts → i-reset-use-case.d.ts}

@@ -1,4 +1,4 @@
-export interface IClearUseCase {
+export interface IResetUseCase {
     run(options: {
         directory?: string;
         skipConfirmation: boolean;

package/dist/infra/cipher/agent/agent-schemas.d.ts

@@ -49,13 +49,13 @@ export declare const FileSystemConfigSchema: z.ZodObject<{
     maxFileSize: z.ZodOptional<z.ZodNumber>;
     workingDirectory: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
+    workingDirectory?: string | undefined;
     allowedExtensions?: string[] | undefined;
     maxFileSize?: number | undefined;
-    workingDirectory?: string | undefined;
 }, {
+    workingDirectory?: string | undefined;
     allowedExtensions?: string[] | undefined;
     maxFileSize?: number | undefined;
-    workingDirectory?: string | undefined;
 }>;
 export type FileSystemConfig = z.input<typeof FileSystemConfigSchema>;
 export type ValidatedFileSystemConfig = z.output<typeof FileSystemConfigSchema>;
@@ -105,13 +105,13 @@ export declare const AgentConfigSchema: z.ZodObject<{
         maxFileSize: z.ZodOptional<z.ZodNumber>;
         workingDirectory: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
+        workingDirectory?: string | undefined;
         allowedExtensions?: string[] | undefined;
         maxFileSize?: number | undefined;
-        workingDirectory?: string | undefined;
     }, {
+        workingDirectory?: string | undefined;
         allowedExtensions?: string[] | undefined;
         maxFileSize?: number | undefined;
-        workingDirectory?: string | undefined;
     }>>;
     httpReferer: z.ZodOptional<z.ZodString>;
     llm: z.ZodDefault<z.ZodObject<{
@@ -182,9 +182,9 @@ export declare const AgentConfigSchema: z.ZodObject<{
         storageDir: string;
     } | undefined;
     fileSystem?: {
+        workingDirectory?: string | undefined;
         allowedExtensions?: string[] | undefined;
         maxFileSize?: number | undefined;
-        workingDirectory?: string | undefined;
     } | undefined;
     httpReferer?: string | undefined;
     openRouterApiKey?: string | undefined;
@@ -208,9 +208,9 @@ export declare const AgentConfigSchema: z.ZodObject<{
         maxTotalSize?: number | undefined;
     } | undefined;
     fileSystem?: {
+        workingDirectory?: string | undefined;
         allowedExtensions?: string[] | undefined;
         maxFileSize?: number | undefined;
-        workingDirectory?: string | undefined;
     } | undefined;
     httpReferer?: string | undefined;
     llm?: {

package/dist/infra/cipher/agent/service-initializer.js

@@ -153,7 +153,7 @@ export async function createCipherAgentServices(config, agentEventBus) {
         // - Existing sessions → BlobHistoryStorage (no migration)
         historyStorage = new DualFormatHistoryStorage(blobHistoryStorage, granularStorage);
         // Create CompactionService for context overflow management
-        const tokenizer = new GeminiTokenizer(config.model ?? 'gemini-2.5-pro');
+        const tokenizer = new GeminiTokenizer(config.model ?? 'gemini-3-flash-preview');
         compactionService = new CompactionService(messageStorage, tokenizer, {
             overflowThreshold: 0.85, // 85% triggers compaction check
             protectedTurns: 2, // Protect first 2 user turns from pruning
@@ -216,7 +216,7 @@ export function createSessionServices(sessionId, sharedServices, httpConfig, llm
             httpReferer: llmConfig.httpReferer,
             maxIterations: llmConfig.maxIterations ?? 50,
             maxTokens: llmConfig.maxTokens ?? 8192,
-            model: llmConfig.model ?? 'google/gemini-2.5-pro',
+            model: llmConfig.model ?? 'google/gemini-3-flash-preview',
             siteName: llmConfig.siteName,
             temperature: llmConfig.temperature ?? 0.7,
             verbose: llmConfig.verbose ?? false,
@@ -244,7 +244,7 @@ export function createSessionServices(sessionId, sharedServices, httpConfig, llm
         // Step 2: Create base content generator
         let generator = new ByteRoverContentGenerator(httpService, {
             maxTokens: llmConfig.maxTokens ?? 8192,
-            model: llmConfig.model ?? 'gemini-2.5-pro',
+            model: llmConfig.model ?? 'gemini-3-flash-preview',
             temperature: llmConfig.temperature ?? 0.7,
         });
         // Step 3: Wrap with retry decorator
@@ -263,7 +263,7 @@ export function createSessionServices(sessionId, sharedServices, httpConfig, llm
         llmService = new ByteRoverLLMService(sessionId, generator, {
             maxIterations: llmConfig.maxIterations ?? 50,
             maxTokens: llmConfig.maxTokens ?? 8192,
-            model: llmConfig.model ?? 'gemini-2.5-pro',
+            model: llmConfig.model ?? 'gemini-3-flash-preview',
             temperature: llmConfig.temperature ?? 0.7,
             verbose: llmConfig.verbose ?? false,
         }, {

package/dist/infra/cipher/file-system/context-tree-file-system-factory.js

@@ -14,8 +14,9 @@ export function createContextTreeFileSystem(baseWorkingDirectory) {
         allowedPaths: ['.'],
         // Use default blocked extensions
         blockedExtensions: ['.exe', '.dll', '.so', '.dylib'],
-        // Block any attempt to escape via parent directory traversal
-        blockedPaths: ['..', '../'],
+        // No additional blocked paths needed - path traversal outside .brv/context-tree/
+        // is prevented by PathValidator.isPathTraversal() and isPathAllowed()
+        blockedPaths: [],
         // Reasonable file size limit
         maxFileSize: 10 * 1024 * 1024, // 10MB
         // Restrict working directory to context tree

package/dist/infra/cipher/file-system/file-system-service.js

@@ -390,6 +390,7 @@ export class FileSystemService {
      * - XML-wrapped output for clearer LLM parsing
      * - Preview metadata (first 20 lines)
      */
+    // eslint-disable-next-line complexity -- Multiple file type handling paths (image/PDF, binary, text) are inherent to the functionality
     async readFile(filePath, options = {}) {
         this.ensureInitialized();
         // Resolve relative paths against working directory

package/dist/infra/cipher/http/internal-llm-http-service.js

@@ -60,8 +60,8 @@ export class ByteRoverLlmHttpService {
         const request = {
             executionMetadata: JSON.stringify(executionMetadata ?? {}),
             params: {
-                config: JSON.stringify(config),
-                contents: JSON.stringify(contents),
+                config,
+                contents,
                 model,
             },
             project_id: this.config.projectId,
@@ -87,9 +87,7 @@ export class ByteRoverLlmHttpService {
         const response = await httpClient.post(url, request, {
             timeout: this.config.timeout,
         });
-        // Parse the JSON string response
-        const content = JSON.parse(response.data);
-        return content;
+        return response.data;
     }
     /**
      * Detect LLM provider from model identifier.

package/dist/infra/cipher/interactive-loop.js

@@ -128,6 +128,7 @@ function setupEventListeners(eventBus, spinnerState) {
         }
         process.stdout.write('\n' + chalk.red(payload.error) + '\n\n');
     };
+    // eslint-disable-next-line no-warning-comments -- Tracked for v0.5.0 release
     // TODO(v0.5.0): Move to outer scope for better performance
     // eslint-disable-next-line unicorn/consistent-function-scoping
     const uiListener = (payload) => {
@@ -167,6 +168,7 @@ function setupEventListeners(eventBus, spinnerState) {
             }
         }
     };
+    // eslint-disable-next-line no-warning-comments -- Tracked for v0.5.0 release
     // TODO(v0.5.0): Move to outer scope for better performance
     // eslint-disable-next-line unicorn/consistent-function-scoping
     const logListener = (payload) => {
@@ -272,7 +274,7 @@ async function executePrompt(prompt, agent, state, eventBus) {
  */
 export async function startInteractiveLoop(agent, options) {
     // Display welcome message
-    displayWelcome(options?.sessionId ?? 'cipher-agent-session', options?.model ?? 'gemini-2.5-pro', options?.eventBus);
+    displayWelcome(options?.sessionId ?? 'cipher-agent-session', options?.model ?? 'gemini-3-flash-preview', options?.eventBus);
     // Create readline interface
     const rl = readline.createInterface({
         input: process.stdin,

package/dist/infra/cipher/llm/context/context-manager.js

@@ -79,10 +79,14 @@ export class ContextManager {
             role: 'assistant',
             toolCalls,
         };
-        this.messages.push(message);
-        // Auto-save to persistent storage (non-blocking)
-        this.persistHistory().catch((error) => {
-            this.logger.error('Failed to persist history after assistant message', { error, sessionId: this.sessionId });
+        await this.mutex.withLock(async () => {
+            this.messages.push(message);
+            try {
+                await this.persistHistory();
+            }
+            catch (error) {
+                this.logger.error('Failed to persist history after assistant message', { error, sessionId: this.sessionId });
+            }
         });
     }
     /**
@@ -95,10 +99,14 @@ export class ContextManager {
             content,
             role: 'system',
         };
-        this.messages.push(message);
-        // Auto-save to persistent storage (non-blocking)
-        this.persistHistory().catch((error) => {
-            this.logger.error('Failed to persist history after system message', { error, sessionId: this.sessionId });
+        await this.mutex.withLock(async () => {
+            this.messages.push(message);
+            try {
+                await this.persistHistory();
+            }
+            catch (error) {
+                this.logger.error('Failed to persist history after system message', { error, sessionId: this.sessionId });
+            }
         });
     }
     /**
@@ -167,16 +175,18 @@ export class ContextManager {
      * @param _fileData - Optional file data (not yet implemented)
      */
     async addUserMessage(content, _imageData, _fileData) {
-        // Simple implementation: just use text content
-        // Image and file support can be added later
         const message = {
             content,
             role: 'user',
         };
-        this.messages.push(message);
-        // Auto-save to persistent storage (non-blocking)
-        this.persistHistory().catch((error) => {
-            this.logger.error('Failed to persist history after user message', { error, sessionId: this.sessionId });
+        await this.mutex.withLock(async () => {
+            this.messages.push(message);
+            try {
+                await this.persistHistory();
+            }
+            catch (error) {
+                this.logger.error('Failed to persist history after user message', { error, sessionId: this.sessionId });
+            }
         });
     }
     /**
@@ -559,8 +569,22 @@ export class ContextManager {
             if (typeof result === 'string') {
                 return result;
             }
-            // Convert to JSON string
-            const jsonString = JSON.stringify(result, null, 2);
+            // Convert to JSON string with special type handling
+            const jsonString = JSON.stringify(result, (_, val) => {
+                // Convert BigInt to string
+                if (typeof val === 'bigint') {
+                    return val.toString();
+                }
+                // Convert functions to their string representation
+                if (typeof val === 'function') {
+                    return `[Function: ${val.name || 'anonymous'}]`;
+                }
+                // Convert Symbols to string
+                if (typeof val === 'symbol') {
+                    return val.toString();
+                }
+                return val;
+            }, 2);
             // Limit size to prevent extremely large results
             const MAX_RESULT_LENGTH = 50_000;
             if (jsonString.length > MAX_RESULT_LENGTH) {

package/dist/infra/cipher/llm/formatters/gemini-formatter.d.ts

@@ -34,6 +34,7 @@ export declare class GeminiMessageFormatter implements IMessageFormatter<Content
     /**
      * Formats assistant message to Gemini's Content format.
      * Maps 'assistant' role to 'model' and includes both text and tool calls.
+     * For Gemini 3+ models, includes thoughtSignature on function calls.
      */
     private formatAssistantMessage;
     /**
@@ -67,3 +68,15 @@ export declare class GeminiMessageFormatter implements IMessageFormatter<Content
      */
     private generateToolCallId;
 }
+/**
+ * Ensures that function calls in the active conversation loop have thought signatures.
+ * Required for Gemini 3+ preview models.
+ *
+ * The "active loop" starts from the last user text message in the conversation.
+ * Only the first function call in each model turn needs a thought signature.
+ *
+ * @param contents Array of Content objects formatted for Gemini API
+ * @param model The model being used (only applies to Gemini 3+ models)
+ * @returns Modified contents with thought signatures added where needed
+ */
+export declare function ensureActiveLoopHasThoughtSignatures(contents: Content[], model: string): Content[];

package/dist/infra/cipher/llm/formatters/gemini-formatter.js

@@ -1,3 +1,10 @@
+import { isGemini3Model, SYNTHETIC_THOUGHT_SIGNATURE } from '../thought-parser.js';
+/**
+ * Type guard to check if a part has a thoughtSignature property.
+ */
+function hasThoughtSignature(part) {
+    return 'thoughtSignature' in part;
+}
 /**
  * Message formatter for Google Gemini API.
  *
@@ -64,24 +71,30 @@ export class GeminiMessageFormatter {
             return [];
         }
         const textParts = [];
-        const functionCalls = [];
+        const functionCallsWithSignatures = [];
         // Extract text and function calls from response parts
         for (const part of candidate.content.parts) {
             if ('text' in part && part.text) {
                 textParts.push(part.text);
             }
             if ('functionCall' in part && part.functionCall) {
-                functionCalls.push(part.functionCall);
+                // Extract thoughtSignature if present (Gemini 3+ models)
+                const thoughtSignature = hasThoughtSignature(part) ? part.thoughtSignature : undefined;
+                functionCallsWithSignatures.push({
+                    fc: part.functionCall,
+                    thoughtSignature,
+                });
             }
         }
         // Convert to internal message format
-        const toolCalls = functionCalls.length > 0
-            ? functionCalls.map((fc) => ({
+        const toolCalls = functionCallsWithSignatures.length > 0
+            ? functionCallsWithSignatures.map(({ fc, thoughtSignature }) => ({
                 function: {
                     arguments: JSON.stringify(fc.args ?? {}),
                     name: fc.name ?? '',
                 },
                 id: this.generateToolCallId(fc.name ?? ''),
+                thoughtSignature,
                 type: 'function',
             }))
             : undefined;
@@ -106,6 +119,7 @@ export class GeminiMessageFormatter {
     /**
      * Formats assistant message to Gemini's Content format.
      * Maps 'assistant' role to 'model' and includes both text and tool calls.
+     * For Gemini 3+ models, includes thoughtSignature on function calls.
      */
     formatAssistantMessage(msg) {
         const parts = [];
@@ -116,12 +130,17 @@ export class GeminiMessageFormatter {
         // Add tool calls if present
         if (msg.toolCalls) {
             for (const tc of msg.toolCalls) {
-                parts.push({
+                const functionCallPart = {
                     functionCall: {
                         args: JSON.parse(tc.function.arguments),
                         name: tc.function.name,
                     },
-                });
+                };
+                // Include thoughtSignature if present (required for Gemini 3+ models)
+                if (tc.thoughtSignature) {
+                    functionCallPart.thoughtSignature = tc.thoughtSignature;
+                }
+                parts.push(functionCallPart);
             }
         }
         return {
@@ -251,3 +270,76 @@ export class GeminiMessageFormatter {
         return `call_${timestamp}_${random}_${toolName}`;
     }
 }
+/**
+ * Ensures that function calls in the active conversation loop have thought signatures.
+ * Required for Gemini 3+ preview models.
+ *
+ * The "active loop" starts from the last user text message in the conversation.
+ * Only the first function call in each model turn needs a thought signature.
+ *
+ * @param contents Array of Content objects formatted for Gemini API
+ * @param model The model being used (only applies to Gemini 3+ models)
+ * @returns Modified contents with thought signatures added where needed
+ */
+export function ensureActiveLoopHasThoughtSignatures(contents, model) {
+    // Only apply to Gemini 3+ models
+    if (!isGemini3Model(model)) {
+        return contents;
+    }
+    // Find the last user turn with text message (start of active loop)
+    let activeLoopStartIndex = -1;
+    for (let i = contents.length - 1; i >= 0; i--) {
+        const content = contents[i];
+        if (content.role === 'user' && content.parts?.some((part) => 'text' in part && part.text)) {
+            activeLoopStartIndex = i;
+            break;
+        }
+    }
+    // No user text message found - nothing to do
+    if (activeLoopStartIndex === -1) {
+        return contents;
+    }
+    // Create shallow copy to avoid mutating original
+    const newContents = [...contents];
+    // Process each content from active loop start to end
+    for (let i = activeLoopStartIndex; i < newContents.length; i++) {
+        const content = newContents[i];
+        // Only process model turns with parts
+        if (content.role !== 'model' || !content.parts) {
+            continue;
+        }
+        const newParts = [...content.parts];
+        const updatedContent = addThoughtSignatureToFirstFunctionCall(newParts, content);
+        if (updatedContent) {
+            newContents[i] = updatedContent;
+        }
+    }
+    return newContents;
+}
+/**
+ * Adds thought signature to the first function call in parts if missing.
+ * Returns updated content or null if no modification needed.
+ */
+function addThoughtSignatureToFirstFunctionCall(parts, content) {
+    for (let j = 0; j < parts.length; j++) {
+        const part = parts[j];
+        if (!part || !('functionCall' in part) || !part.functionCall) {
+            continue;
+        }
+        // Check if thoughtSignature already exists using type guard
+        if (hasThoughtSignature(part) && part.thoughtSignature) {
+            return null; // Already has signature, no modification needed
+        }
+        // Add synthetic thought signature
+        const partWithSignature = {
+            ...part,
+            thoughtSignature: SYNTHETIC_THOUGHT_SIGNATURE,
+        };
+        parts[j] = partWithSignature;
+        return {
+            ...content,
+            parts,
+        };
+    }
+    return null; // No function call found
+}