@maintainer-pro/ai-cli 0.1.4 → 0.1.5

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { Logger } from 'pino';
+export { Logger } from 'pino';
 import { z } from 'zod';
 
 type AiCliProviderId = "claude" | "cursor" | "antigravity" | (string & {});
@@ -54,6 +56,11 @@ interface CallAiOptions {
      * Injected into the prompt for the model to use when relevant.
      */
     priorConversationsContext?: string;
+    /**
+     * Explicit reply-to parent chain (oldest → newest ancestor of the current
+     * user message). Injected so the model anchors on the thread being answered.
+     */
+    parentChainContext?: string;
     /** Extra / override providers (e.g. future HTTP model backends). */
     providers?: AiProvider[];
     /** When true, skip the end-user chat footer so the agent can return structured output. */
@@ -84,18 +91,97 @@ declare function providerLabel(providerId: string): string;
 /** Extract ```json ... ``` tool blocks and strip them from assistant text. */
 declare function parseAiResponse(raw: string, provider: AiCliProviderId): AiResponse;
 
+/** Stable delimiters so models can weight sections distinctly. */
+declare const PROMPT_SECTION: {
+    readonly system: {
+        readonly begin: "<<<SYSTEM_BEGIN>>>";
+        readonly end: "<<<SYSTEM_END>>>";
+    };
+    readonly clientContext: {
+        readonly begin: "<<<CLIENT_CONTEXT_BEGIN>>>";
+        readonly end: "<<<CLIENT_CONTEXT_END>>>";
+    };
+    readonly priorConversations: {
+        readonly begin: "<<<PRIOR_CONVERSATIONS_BEGIN>>>";
+        readonly end: "<<<PRIOR_CONVERSATIONS_END>>>";
+    };
+    readonly parentChain: {
+        readonly begin: "<<<PARENT_CHAIN_BEGIN>>>";
+        readonly end: "<<<PARENT_CHAIN_END>>>";
+    };
+    readonly history: {
+        readonly begin: "<<<CONVERSATION_HISTORY_BEGIN>>>";
+        readonly end: "<<<CONVERSATION_HISTORY_END>>>";
+    };
+    readonly attachments: {
+        readonly begin: "<<<ATTACHMENTS_BEGIN>>>";
+        readonly end: "<<<ATTACHMENTS_END>>>";
+    };
+    readonly currentRequest: {
+        readonly begin: "<<<CURRENT_REQUEST_BEGIN>>>";
+        readonly end: "<<<CURRENT_REQUEST_END>>>";
+    };
+};
 declare function buildConversationPrompt(messages: ChatMessage[]): string;
 declare function formatClientContext(context?: ClientContext): string;
 /** Full prompt for providers without a native --system-prompt flag (Cursor). */
-declare function buildCursorPrompt(systemPrompt: string, messages: ChatMessage[], context?: ClientContext, attachmentPaths?: string[], priorConversationsContext?: string, technical?: boolean): string;
+declare function buildCursorPrompt(systemPrompt: string, messages: ChatMessage[], context?: ClientContext, attachmentPaths?: string[], priorConversationsContext?: string, technical?: boolean, parentChainContext?: string): string;
 /** Conversation + context for Claude (system prompt passed separately). */
-declare function buildClaudeUserPrompt(messages: ChatMessage[], context?: ClientContext, attachmentPaths?: string[], priorConversationsContext?: string, technical?: boolean): string;
+declare function buildClaudeUserPrompt(messages: ChatMessage[], context?: ClientContext, attachmentPaths?: string[], priorConversationsContext?: string, technical?: boolean, parentChainContext?: string): string;
+
+/** Stored row fields needed to walk reply-to links. */
+type ParentChainSource = {
+    id: string;
+    role: string;
+    content: string;
+    parentMessageId?: string | null;
+    senderName?: string | null;
+    provider?: string | null;
+};
+type ParentChainEntry = {
+    id: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    senderName?: string;
+};
+/**
+ * Walk `parentMessageId` from `startId` up to the root (oldest first).
+ * Skips empty / working placeholders.
+ */
+declare function collectParentChain(rows: ParentChainSource[], startId: string | null | undefined): ParentChainEntry[];
+/**
+ * Resolve the reply-to id for the current user turn, then walk ancestors.
+ * `currentMessageId` is the user message being answered this turn.
+ */
+declare function parentChainForTurn(rows: ParentChainSource[], currentMessageId: string | null | undefined, fallbackParentId?: string | null): ParentChainEntry[];
+/** Prompt block so the model treats the chain as the reply target. */
+declare function formatParentChainContext(chain: ParentChainEntry[]): string;
 
 declare function createDefaultSystemPrompt(input: {
     productDescription: string;
     relevantFilesHint?: string;
     runtimeToolsHint?: string;
+    /** Relative ignore globs (already merged with defaults). */
+    ignorePaths?: string[];
+}): string;
+
+/** Always blocked relative to the project folder (secrets / credentials). */
+declare const DEFAULT_AI_IGNORE_PATHS: readonly [".env", ".env.*", "**/.env", "**/.env.*"];
+declare function parseIgnorePathsEnv(raw: string | undefined | null): string[];
+declare function normalizeIgnorePaths(paths: string[]): string[];
+/** Partner paths plus built-in secret ignores (deduped). */
+declare function resolveIgnorePaths(partnerPaths: string[]): string[];
+declare function isInsideWorkspace(workspaceDir: string, targetPath: string): boolean;
+declare function isIgnoredRelative(relativePath: string, patterns: string[]): boolean;
+declare function isPathAllowed(workspaceDir: string, targetPath: string, ignorePaths: string[]): boolean;
+declare function formatAccessPolicyPromptSection(input: {
+    ignorePaths: string[];
 }): string;
+/** Marker block written into .cursorignore (and similar) by the bridge. */
+declare const ACCESS_IGNORE_BEGIN = "# maintainer-pro:access-begin";
+declare const ACCESS_IGNORE_END = "# maintainer-pro:access-end";
+declare function renderManagedIgnoreBlock(ignorePaths: string[]): string;
+declare function upsertManagedIgnoreFile(existing: string, ignorePaths: string[]): string;
 
 declare function createClaudeProvider(): AiProvider;
 
@@ -103,6 +189,29 @@ declare function createCursorProvider(): AiProvider;
 
 declare function createAntigravityProvider(): AiProvider;
 
+/** True when NODE_ENV / AI_ENV is development (or AI_DEV=1). */
+declare function isDevMode(): boolean;
+/**
+ * Resolve log level from env.
+ * Defaults to `debug` in development, otherwise `info`.
+ * Override anytime with LOG_LEVEL / AI_LOG_LEVEL.
+ */
+declare function resolveLogLevel(): string;
+/**
+ * Shared logger for Maintainer Pro Node packages.
+ *
+ * Levels: fatal | error | warn | info | debug | trace | silent
+ * - Dev (`NODE_ENV=development` or unset on local sidecars): default `debug`
+ * - Production: default `info`
+ * - Override: `LOG_LEVEL=debug` / `AI_LOG_LEVEL`
+ * - Pretty TTY output (disable with `LOG_PRETTY=0`)
+ */
+declare function createLogger(name: string): Logger;
+/** Adapter for older `(msg) => void` callbacks — logs at info. */
+declare function createInfoLogger(name: string): (msg: string) => void;
+/** Short preview for debug logs (never dump huge prompts). */
+declare function previewText(text: string | undefined | null, max?: number): string;
+
 type ToolSchemaMap = Record<string, z.ZodTypeAny>;
 declare function createToolValidator(schemas: ToolSchemaMap): (toolCall: ToolCall) => {
     valid: true;
@@ -120,13 +229,27 @@ interface ChatStoreLike {
     ensureConversation(id: string): Promise<void>;
     saveMessage(input: {
         conversationId: string;
+        id?: string;
         role: "user" | "assistant" | "system";
         content: string;
         provider?: string;
         attachmentPaths?: string[];
         senderType?: "client" | "developer" | "ai";
         senderName?: string;
-    }): Promise<unknown>;
+        /** Reply chain: assistant/working rows point at the user message. */
+        parentMessageId?: string | null;
+        /** queue = persist only; run = this user turn starts the AI. */
+        intent?: "queue" | "run";
+        queueStatus?: "working" | "queued" | null;
+    }): Promise<{
+        id: string;
+        queueStatus?: string | null;
+        queuePosition?: number | null;
+        nextQueued?: {
+            id: string;
+            content: string;
+        } | null;
+    } | unknown>;
     listMessages?(conversationId: string): Promise<Array<{
         id: string;
         role: string;
@@ -136,9 +259,29 @@ interface ChatStoreLike {
         attachmentPaths?: string[];
         senderType?: "client" | "developer" | "ai" | null;
         senderName?: string | null;
+        parentMessageId?: string | null;
+        queueStatus?: string | null;
+        queuePosition?: number | null;
     }>>;
     /** Remove in-progress working placeholders (at most one per conversation). */
     clearWorkingMessages?(conversationId: string): Promise<void>;
+    /** Clear the working user turn and promote the oldest queued message. */
+    releaseWorkingTurn?(conversationId: string, parentMessageId?: string | null): Promise<{
+        nextQueued?: {
+            id: string;
+            content: string;
+        } | null;
+    } | void>;
+    /** Unstick working/queued turns after crashes or raced promotes. */
+    recoverQueue?(conversationId: string): Promise<{
+        action: string;
+        workingId?: string | null;
+        promotedId?: string | null;
+        nextQueued?: {
+            id: string;
+            content: string;
+        } | null;
+    } | void>;
     /** All conversations under the store (for prior-chat context). */
     listConversations?(): Promise<Array<{
         id: string;
@@ -173,6 +316,7 @@ interface ChatHandlerOptions {
     db?: ChatStoreLike;
     conversationId?: string | ((request: Request) => string | undefined);
     onToolCalls?: (toolCalls: ToolCall[], context?: ClientContext) => void | Promise<void>;
+    logger?: Logger;
 }
 interface ChatHandlers {
     GET: (request: Request) => Promise<Response>;
@@ -197,6 +341,9 @@ interface LocalStoredMessage {
     attachmentPaths?: string[];
     senderType?: "client" | "developer" | "ai" | null;
     senderName?: string | null;
+    parentMessageId?: string | null;
+    queueStatus?: string | null;
+    queuePosition?: number | null;
 }
 /**
  * Persist conversations as JSON files under a local directory.
@@ -207,12 +354,61 @@ declare function createLocalDirectoryStore(baseDir: string): ChatStoreLike & {
     listConversations: NonNullable<ChatStoreLike["listConversations"]>;
 };
 
+type CachedChatMessage = NonNullable<Awaited<ReturnType<NonNullable<ChatStoreLike["listMessages"]>>>>[number];
+type CachedConversation = {
+    id: string;
+    updatedAt: string;
+    messages: CachedChatMessage[];
+};
+type SyncedStoreStats = {
+    conversations: number;
+    messages: number;
+};
+type SyncedChatStore = ChatStoreLike & {
+    uploadAttachments?: NonNullable<ChatStoreLike["uploadAttachments"]>;
+    ready: Promise<SyncedStoreStats>;
+    stop: () => void;
+};
+type RemoteStore = ChatStoreLike & {
+    uploadAttachments?: NonNullable<ChatStoreLike["uploadAttachments"]>;
+    listSnapshot?: () => Promise<CachedConversation[]>;
+};
+type WorkingTurnEvent = {
+    conversationId: string;
+    message: CachedChatMessage;
+};
+type SyncedChatStoreOptions = {
+    remote: RemoteStore;
+    maintainerProUrl: string;
+    apiKey: string;
+    /** Pino logger. Prefer this over `log`. */
+    logger?: Logger;
+    /** @deprecated Prefer `logger`. Info-level string messages only. */
+    log?: (msg: string) => void;
+    onWorkingTurn?: (event: WorkingTurnEvent) => void;
+};
+/**
+ * In-memory message cache in front of a remote Maintainer Pro store.
+ * Hydrates a full snapshot on start, writes through on local changes,
+ * and applies live WebSocket events from the other party.
+ */
+declare function createSyncedChatStore(options: SyncedChatStoreOptions): SyncedChatStore;
+
 interface MaintainerProStoreOptions {
     baseUrl: string;
     apiKey: string;
     /** Directory for temporary local copies of images for CLI providers. */
     tempDir?: string;
     fetchImpl?: typeof fetch;
+    /**
+     * Keep a local message cache and live-sync over WebSocket.
+     * Default true. Set false for HTTP-only (tests / one-shot scripts).
+     */
+    sync?: boolean;
+    logger?: Logger;
+    /** @deprecated Prefer `logger`. */
+    log?: (msg: string) => void;
+    onWorkingTurn?: (event: WorkingTurnEvent) => void;
 }
 type UploadResult = {
     /** Refs persisted on messages (maintainer-pro://uuid). */
@@ -224,11 +420,16 @@ type UploadResult = {
 /**
  * Persist chat data via Maintainer Pro HTTP API (no local .maintainer-pro writes).
  */
-declare function createMaintainerProStore(options: MaintainerProStoreOptions): ChatStoreLike & {
+declare function createMaintainerProStore(options: MaintainerProStoreOptions): SyncedChatStore & {
     uploadAttachments: (conversationId: string, attachments: ChatAttachment[] | undefined) => Promise<UploadResult>;
 };
 /** Build a Maintainer Pro store from env when configured. */
-declare function createMaintainerProStoreFromEnv(): ReturnType<typeof createMaintainerProStore> | null;
+declare function createMaintainerProStoreFromEnv(options?: {
+    logger?: Logger;
+    log?: (msg: string) => void;
+    sync?: boolean;
+    onWorkingTurn?: (event: WorkingTurnEvent) => void;
+}): ReturnType<typeof createMaintainerProStore> | null;
 
 interface PriorConversationOptions {
     excludeConversationId?: string;
@@ -278,4 +479,4 @@ interface WorkspaceInspectResult {
  */
 declare function inspectAndRepairWorkspace(input: WorkspaceInspectInput): Promise<WorkspaceInspectResult>;
 
-export { type AiCliProviderId, type AiProvider, type AiResponse, type CallAiOptions, type ChatAttachment, type ChatHandlerOptions, type ChatHandlers, type ChatMessage, type ChatSenderType, type ChatStoreLike, type ChatUser, type ClientContext, type LocalStoredMessage, type MaintainerProStoreOptions, type PriorConversationOptions, type ProviderPreference, type ToolCall, type ToolSchemaMap, WORKING_PROVIDER, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceKind, buildClaudeUserPrompt, buildConversationPrompt, buildCursorPrompt, buildPriorConversationsContext, callAi, commandExists, createAntigravityProvider, createBuiltinProviders, createChatHandler, createClaudeProvider, createCursorProvider, createDefaultSystemPrompt, createLocalDirectoryStore, createMaintainerProStore, createMaintainerProStoreFromEnv, createToolValidator, formatClientContext, getProviderPreference, inspectAndRepairWorkspace, parseAiResponse, providerLabel, resolveCliBinary, resolveProvider, saveChatAttachments, toNextRoute };
+export { ACCESS_IGNORE_BEGIN, ACCESS_IGNORE_END, type AiCliProviderId, type AiProvider, type AiResponse, type CachedChatMessage, type CachedConversation, type CallAiOptions, type ChatAttachment, type ChatHandlerOptions, type ChatHandlers, type ChatMessage, type ChatSenderType, type ChatStoreLike, type ChatUser, type ClientContext, DEFAULT_AI_IGNORE_PATHS, type LocalStoredMessage, type MaintainerProStoreOptions, PROMPT_SECTION, type ParentChainEntry, type ParentChainSource, type PriorConversationOptions, type ProviderPreference, type SyncedChatStore, type SyncedChatStoreOptions, type SyncedStoreStats, type ToolCall, type ToolSchemaMap, WORKING_PROVIDER, type WorkingTurnEvent, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceKind, buildClaudeUserPrompt, buildConversationPrompt, buildCursorPrompt, buildPriorConversationsContext, callAi, collectParentChain, commandExists, createAntigravityProvider, createBuiltinProviders, createChatHandler, createClaudeProvider, createCursorProvider, createDefaultSystemPrompt, createInfoLogger, createLocalDirectoryStore, createLogger, createMaintainerProStore, createMaintainerProStoreFromEnv, createSyncedChatStore, createToolValidator, formatAccessPolicyPromptSection, formatClientContext, formatParentChainContext, getProviderPreference, inspectAndRepairWorkspace, isDevMode, isIgnoredRelative, isInsideWorkspace, isPathAllowed, normalizeIgnorePaths, parentChainForTurn, parseAiResponse, parseIgnorePathsEnv, previewText, providerLabel, renderManagedIgnoreBlock, resolveCliBinary, resolveIgnorePaths, resolveLogLevel, resolveProvider, saveChatAttachments, toNextRoute, upsertManagedIgnoreFile };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { Logger } from 'pino';
+export { Logger } from 'pino';
 import { z } from 'zod';
 
 type AiCliProviderId = "claude" | "cursor" | "antigravity" | (string & {});
@@ -54,6 +56,11 @@ interface CallAiOptions {
      * Injected into the prompt for the model to use when relevant.
      */
     priorConversationsContext?: string;
+    /**
+     * Explicit reply-to parent chain (oldest → newest ancestor of the current
+     * user message). Injected so the model anchors on the thread being answered.
+     */
+    parentChainContext?: string;
     /** Extra / override providers (e.g. future HTTP model backends). */
     providers?: AiProvider[];
     /** When true, skip the end-user chat footer so the agent can return structured output. */
@@ -84,18 +91,97 @@ declare function providerLabel(providerId: string): string;
 /** Extract ```json ... ``` tool blocks and strip them from assistant text. */
 declare function parseAiResponse(raw: string, provider: AiCliProviderId): AiResponse;
 
+/** Stable delimiters so models can weight sections distinctly. */
+declare const PROMPT_SECTION: {
+    readonly system: {
+        readonly begin: "<<<SYSTEM_BEGIN>>>";
+        readonly end: "<<<SYSTEM_END>>>";
+    };
+    readonly clientContext: {
+        readonly begin: "<<<CLIENT_CONTEXT_BEGIN>>>";
+        readonly end: "<<<CLIENT_CONTEXT_END>>>";
+    };
+    readonly priorConversations: {
+        readonly begin: "<<<PRIOR_CONVERSATIONS_BEGIN>>>";
+        readonly end: "<<<PRIOR_CONVERSATIONS_END>>>";
+    };
+    readonly parentChain: {
+        readonly begin: "<<<PARENT_CHAIN_BEGIN>>>";
+        readonly end: "<<<PARENT_CHAIN_END>>>";
+    };
+    readonly history: {
+        readonly begin: "<<<CONVERSATION_HISTORY_BEGIN>>>";
+        readonly end: "<<<CONVERSATION_HISTORY_END>>>";
+    };
+    readonly attachments: {
+        readonly begin: "<<<ATTACHMENTS_BEGIN>>>";
+        readonly end: "<<<ATTACHMENTS_END>>>";
+    };
+    readonly currentRequest: {
+        readonly begin: "<<<CURRENT_REQUEST_BEGIN>>>";
+        readonly end: "<<<CURRENT_REQUEST_END>>>";
+    };
+};
 declare function buildConversationPrompt(messages: ChatMessage[]): string;
 declare function formatClientContext(context?: ClientContext): string;
 /** Full prompt for providers without a native --system-prompt flag (Cursor). */
-declare function buildCursorPrompt(systemPrompt: string, messages: ChatMessage[], context?: ClientContext, attachmentPaths?: string[], priorConversationsContext?: string, technical?: boolean): string;
+declare function buildCursorPrompt(systemPrompt: string, messages: ChatMessage[], context?: ClientContext, attachmentPaths?: string[], priorConversationsContext?: string, technical?: boolean, parentChainContext?: string): string;
 /** Conversation + context for Claude (system prompt passed separately). */
-declare function buildClaudeUserPrompt(messages: ChatMessage[], context?: ClientContext, attachmentPaths?: string[], priorConversationsContext?: string, technical?: boolean): string;
+declare function buildClaudeUserPrompt(messages: ChatMessage[], context?: ClientContext, attachmentPaths?: string[], priorConversationsContext?: string, technical?: boolean, parentChainContext?: string): string;
+
+/** Stored row fields needed to walk reply-to links. */
+type ParentChainSource = {
+    id: string;
+    role: string;
+    content: string;
+    parentMessageId?: string | null;
+    senderName?: string | null;
+    provider?: string | null;
+};
+type ParentChainEntry = {
+    id: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    senderName?: string;
+};
+/**
+ * Walk `parentMessageId` from `startId` up to the root (oldest first).
+ * Skips empty / working placeholders.
+ */
+declare function collectParentChain(rows: ParentChainSource[], startId: string | null | undefined): ParentChainEntry[];
+/**
+ * Resolve the reply-to id for the current user turn, then walk ancestors.
+ * `currentMessageId` is the user message being answered this turn.
+ */
+declare function parentChainForTurn(rows: ParentChainSource[], currentMessageId: string | null | undefined, fallbackParentId?: string | null): ParentChainEntry[];
+/** Prompt block so the model treats the chain as the reply target. */
+declare function formatParentChainContext(chain: ParentChainEntry[]): string;
 
 declare function createDefaultSystemPrompt(input: {
     productDescription: string;
     relevantFilesHint?: string;
     runtimeToolsHint?: string;
+    /** Relative ignore globs (already merged with defaults). */
+    ignorePaths?: string[];
+}): string;
+
+/** Always blocked relative to the project folder (secrets / credentials). */
+declare const DEFAULT_AI_IGNORE_PATHS: readonly [".env", ".env.*", "**/.env", "**/.env.*"];
+declare function parseIgnorePathsEnv(raw: string | undefined | null): string[];
+declare function normalizeIgnorePaths(paths: string[]): string[];
+/** Partner paths plus built-in secret ignores (deduped). */
+declare function resolveIgnorePaths(partnerPaths: string[]): string[];
+declare function isInsideWorkspace(workspaceDir: string, targetPath: string): boolean;
+declare function isIgnoredRelative(relativePath: string, patterns: string[]): boolean;
+declare function isPathAllowed(workspaceDir: string, targetPath: string, ignorePaths: string[]): boolean;
+declare function formatAccessPolicyPromptSection(input: {
+    ignorePaths: string[];
 }): string;
+/** Marker block written into .cursorignore (and similar) by the bridge. */
+declare const ACCESS_IGNORE_BEGIN = "# maintainer-pro:access-begin";
+declare const ACCESS_IGNORE_END = "# maintainer-pro:access-end";
+declare function renderManagedIgnoreBlock(ignorePaths: string[]): string;
+declare function upsertManagedIgnoreFile(existing: string, ignorePaths: string[]): string;
 
 declare function createClaudeProvider(): AiProvider;
 
@@ -103,6 +189,29 @@ declare function createCursorProvider(): AiProvider;
 
 declare function createAntigravityProvider(): AiProvider;
 
+/** True when NODE_ENV / AI_ENV is development (or AI_DEV=1). */
+declare function isDevMode(): boolean;
+/**
+ * Resolve log level from env.
+ * Defaults to `debug` in development, otherwise `info`.
+ * Override anytime with LOG_LEVEL / AI_LOG_LEVEL.
+ */
+declare function resolveLogLevel(): string;
+/**
+ * Shared logger for Maintainer Pro Node packages.
+ *
+ * Levels: fatal | error | warn | info | debug | trace | silent
+ * - Dev (`NODE_ENV=development` or unset on local sidecars): default `debug`
+ * - Production: default `info`
+ * - Override: `LOG_LEVEL=debug` / `AI_LOG_LEVEL`
+ * - Pretty TTY output (disable with `LOG_PRETTY=0`)
+ */
+declare function createLogger(name: string): Logger;
+/** Adapter for older `(msg) => void` callbacks — logs at info. */
+declare function createInfoLogger(name: string): (msg: string) => void;
+/** Short preview for debug logs (never dump huge prompts). */
+declare function previewText(text: string | undefined | null, max?: number): string;
+
 type ToolSchemaMap = Record<string, z.ZodTypeAny>;
 declare function createToolValidator(schemas: ToolSchemaMap): (toolCall: ToolCall) => {
     valid: true;
@@ -120,13 +229,27 @@ interface ChatStoreLike {
     ensureConversation(id: string): Promise<void>;
     saveMessage(input: {
         conversationId: string;
+        id?: string;
         role: "user" | "assistant" | "system";
         content: string;
         provider?: string;
         attachmentPaths?: string[];
         senderType?: "client" | "developer" | "ai";
         senderName?: string;
-    }): Promise<unknown>;
+        /** Reply chain: assistant/working rows point at the user message. */
+        parentMessageId?: string | null;
+        /** queue = persist only; run = this user turn starts the AI. */
+        intent?: "queue" | "run";
+        queueStatus?: "working" | "queued" | null;
+    }): Promise<{
+        id: string;
+        queueStatus?: string | null;
+        queuePosition?: number | null;
+        nextQueued?: {
+            id: string;
+            content: string;
+        } | null;
+    } | unknown>;
     listMessages?(conversationId: string): Promise<Array<{
         id: string;
         role: string;
@@ -136,9 +259,29 @@ interface ChatStoreLike {
         attachmentPaths?: string[];
         senderType?: "client" | "developer" | "ai" | null;
         senderName?: string | null;
+        parentMessageId?: string | null;
+        queueStatus?: string | null;
+        queuePosition?: number | null;
     }>>;
     /** Remove in-progress working placeholders (at most one per conversation). */
     clearWorkingMessages?(conversationId: string): Promise<void>;
+    /** Clear the working user turn and promote the oldest queued message. */
+    releaseWorkingTurn?(conversationId: string, parentMessageId?: string | null): Promise<{
+        nextQueued?: {
+            id: string;
+            content: string;
+        } | null;
+    } | void>;
+    /** Unstick working/queued turns after crashes or raced promotes. */
+    recoverQueue?(conversationId: string): Promise<{
+        action: string;
+        workingId?: string | null;
+        promotedId?: string | null;
+        nextQueued?: {
+            id: string;
+            content: string;
+        } | null;
+    } | void>;
     /** All conversations under the store (for prior-chat context). */
     listConversations?(): Promise<Array<{
         id: string;
@@ -173,6 +316,7 @@ interface ChatHandlerOptions {
     db?: ChatStoreLike;
     conversationId?: string | ((request: Request) => string | undefined);
     onToolCalls?: (toolCalls: ToolCall[], context?: ClientContext) => void | Promise<void>;
+    logger?: Logger;
 }
 interface ChatHandlers {
     GET: (request: Request) => Promise<Response>;
@@ -197,6 +341,9 @@ interface LocalStoredMessage {
     attachmentPaths?: string[];
     senderType?: "client" | "developer" | "ai" | null;
     senderName?: string | null;
+    parentMessageId?: string | null;
+    queueStatus?: string | null;
+    queuePosition?: number | null;
 }
 /**
  * Persist conversations as JSON files under a local directory.
@@ -207,12 +354,61 @@ declare function createLocalDirectoryStore(baseDir: string): ChatStoreLike & {
     listConversations: NonNullable<ChatStoreLike["listConversations"]>;
 };
 
+type CachedChatMessage = NonNullable<Awaited<ReturnType<NonNullable<ChatStoreLike["listMessages"]>>>>[number];
+type CachedConversation = {
+    id: string;
+    updatedAt: string;
+    messages: CachedChatMessage[];
+};
+type SyncedStoreStats = {
+    conversations: number;
+    messages: number;
+};
+type SyncedChatStore = ChatStoreLike & {
+    uploadAttachments?: NonNullable<ChatStoreLike["uploadAttachments"]>;
+    ready: Promise<SyncedStoreStats>;
+    stop: () => void;
+};
+type RemoteStore = ChatStoreLike & {
+    uploadAttachments?: NonNullable<ChatStoreLike["uploadAttachments"]>;
+    listSnapshot?: () => Promise<CachedConversation[]>;
+};
+type WorkingTurnEvent = {
+    conversationId: string;
+    message: CachedChatMessage;
+};
+type SyncedChatStoreOptions = {
+    remote: RemoteStore;
+    maintainerProUrl: string;
+    apiKey: string;
+    /** Pino logger. Prefer this over `log`. */
+    logger?: Logger;
+    /** @deprecated Prefer `logger`. Info-level string messages only. */
+    log?: (msg: string) => void;
+    onWorkingTurn?: (event: WorkingTurnEvent) => void;
+};
+/**
+ * In-memory message cache in front of a remote Maintainer Pro store.
+ * Hydrates a full snapshot on start, writes through on local changes,
+ * and applies live WebSocket events from the other party.
+ */
+declare function createSyncedChatStore(options: SyncedChatStoreOptions): SyncedChatStore;
+
 interface MaintainerProStoreOptions {
     baseUrl: string;
     apiKey: string;
     /** Directory for temporary local copies of images for CLI providers. */
     tempDir?: string;
     fetchImpl?: typeof fetch;
+    /**
+     * Keep a local message cache and live-sync over WebSocket.
+     * Default true. Set false for HTTP-only (tests / one-shot scripts).
+     */
+    sync?: boolean;
+    logger?: Logger;
+    /** @deprecated Prefer `logger`. */
+    log?: (msg: string) => void;
+    onWorkingTurn?: (event: WorkingTurnEvent) => void;
 }
 type UploadResult = {
     /** Refs persisted on messages (maintainer-pro://uuid). */
@@ -224,11 +420,16 @@ type UploadResult = {
 /**
  * Persist chat data via Maintainer Pro HTTP API (no local .maintainer-pro writes).
  */
-declare function createMaintainerProStore(options: MaintainerProStoreOptions): ChatStoreLike & {
+declare function createMaintainerProStore(options: MaintainerProStoreOptions): SyncedChatStore & {
     uploadAttachments: (conversationId: string, attachments: ChatAttachment[] | undefined) => Promise<UploadResult>;
 };
 /** Build a Maintainer Pro store from env when configured. */
-declare function createMaintainerProStoreFromEnv(): ReturnType<typeof createMaintainerProStore> | null;
+declare function createMaintainerProStoreFromEnv(options?: {
+    logger?: Logger;
+    log?: (msg: string) => void;
+    sync?: boolean;
+    onWorkingTurn?: (event: WorkingTurnEvent) => void;
+}): ReturnType<typeof createMaintainerProStore> | null;
 
 interface PriorConversationOptions {
     excludeConversationId?: string;
@@ -278,4 +479,4 @@ interface WorkspaceInspectResult {
  */
 declare function inspectAndRepairWorkspace(input: WorkspaceInspectInput): Promise<WorkspaceInspectResult>;
 
-export { type AiCliProviderId, type AiProvider, type AiResponse, type CallAiOptions, type ChatAttachment, type ChatHandlerOptions, type ChatHandlers, type ChatMessage, type ChatSenderType, type ChatStoreLike, type ChatUser, type ClientContext, type LocalStoredMessage, type MaintainerProStoreOptions, type PriorConversationOptions, type ProviderPreference, type ToolCall, type ToolSchemaMap, WORKING_PROVIDER, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceKind, buildClaudeUserPrompt, buildConversationPrompt, buildCursorPrompt, buildPriorConversationsContext, callAi, commandExists, createAntigravityProvider, createBuiltinProviders, createChatHandler, createClaudeProvider, createCursorProvider, createDefaultSystemPrompt, createLocalDirectoryStore, createMaintainerProStore, createMaintainerProStoreFromEnv, createToolValidator, formatClientContext, getProviderPreference, inspectAndRepairWorkspace, parseAiResponse, providerLabel, resolveCliBinary, resolveProvider, saveChatAttachments, toNextRoute };
+export { ACCESS_IGNORE_BEGIN, ACCESS_IGNORE_END, type AiCliProviderId, type AiProvider, type AiResponse, type CachedChatMessage, type CachedConversation, type CallAiOptions, type ChatAttachment, type ChatHandlerOptions, type ChatHandlers, type ChatMessage, type ChatSenderType, type ChatStoreLike, type ChatUser, type ClientContext, DEFAULT_AI_IGNORE_PATHS, type LocalStoredMessage, type MaintainerProStoreOptions, PROMPT_SECTION, type ParentChainEntry, type ParentChainSource, type PriorConversationOptions, type ProviderPreference, type SyncedChatStore, type SyncedChatStoreOptions, type SyncedStoreStats, type ToolCall, type ToolSchemaMap, WORKING_PROVIDER, type WorkingTurnEvent, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceKind, buildClaudeUserPrompt, buildConversationPrompt, buildCursorPrompt, buildPriorConversationsContext, callAi, collectParentChain, commandExists, createAntigravityProvider, createBuiltinProviders, createChatHandler, createClaudeProvider, createCursorProvider, createDefaultSystemPrompt, createInfoLogger, createLocalDirectoryStore, createLogger, createMaintainerProStore, createMaintainerProStoreFromEnv, createSyncedChatStore, createToolValidator, formatAccessPolicyPromptSection, formatClientContext, formatParentChainContext, getProviderPreference, inspectAndRepairWorkspace, isDevMode, isIgnoredRelative, isInsideWorkspace, isPathAllowed, normalizeIgnorePaths, parentChainForTurn, parseAiResponse, parseIgnorePathsEnv, previewText, providerLabel, renderManagedIgnoreBlock, resolveCliBinary, resolveIgnorePaths, resolveLogLevel, resolveProvider, saveChatAttachments, toNextRoute, upsertManagedIgnoreFile };