thatgfsj-code 2.2.9 → 3.0.0

package/dist/llm/index.js

@@ -1,6 +1,14 @@
 /**
  * LLM Service - Factory for creating providers
  * Supports all providers + custom relay stations (中转站)
+ *
+ * v3.0.0+: streaming protocol migrated to structured StreamChunk
+ *   - chatStream yields { type: 'text' | 'tool_calls' | 'thinking' | 'usage' }
+ *   - Tool call execution is now part of the agent loop; consumers see
+ *     { type: 'tool_calls', toolCalls } for dispatch and { type: 'text', content }
+ *     for model output. The legacy @@TOOL@@ sentinel-string protocol is GONE.
+ *   - Usage / cache stats are emitted as the final { type: 'usage' } chunk,
+ *     which the TUI cache stats store consumes.
  */
 import { PROVIDERS } from '../config/providers.js';
 import { OpenAIProvider } from './openai.js';
@@ -23,6 +31,9 @@ export class LLMService {
             baseUrl: config.baseUrl || providerConfig.baseUrl,
             temperature: config.temperature ?? 0.7,
             maxTokens: config.maxTokens ?? 4096,
+            // v3.0.0: forward cache policy. Anthropic reads this to decide
+            // whether to attach cache_control markers; other providers ignore it.
+            cache: config.cache ?? { enabled: true, ttl: '5m', strategy: 'auto' },
         };
         const format = providerConfig.format;
         let provider;
@@ -52,10 +63,18 @@ export class LLMService {
         return this.provider.chat(messages, options, toolsArray.length > 0 ? toolsArray : undefined);
     }
     /**
-     * Streaming chat with agent loop (tool call support)
-     * - Streams text to the user
-     * - Detects structured tool calls from the API
-     * - Executes tools and loops back for more
+     * Streaming chat with agent loop (tool call support).
+     *
+     * Structured chunk protocol (replaces the @@TOOL@@ sentinel strings):
+     *   { type: 'text',       content: string }      model output, accumulate + render
+     *   { type: 'tool_calls', toolCalls: ToolCall[] } dispatch tools, results will
+     *                                                be folded into the next request
+     *   { type: 'thinking',   content: string }      reasoning text (consumers may
+     *                                                display in debug mode)
+     *   { type: 'usage',      usage: Usage }         cache hit/miss + token counts;
+     *                                                emitted on the final round
+     *
+     * Returns the final ChatResponse of the agent loop when done.
      */
     async *chatStream(messages, options) {
         if (!this.hasApiKey())
@@ -63,44 +82,74 @@ export class LLMService {
         const maxIterations = options?.maxIterations ?? 10;
         let currentMessages = [...messages];
         let iterations = 0;
+        let lastUsage;
         while (iterations < maxIterations) {
             iterations++;
             const toolsArray = [...this.tools.values()];
             const hasTools = toolsArray.length > 0;
             let fullContent = '';
             let detectedToolCalls;
+            // Forward stream chunks from the provider. We collect text internally for
+            // tool-call persistence but always re-emit the original chunks unchanged.
             const stream = this.provider.chatStream(currentMessages, options, hasTools ? toolsArray : undefined);
             for await (const chunk of stream) {
                 if (chunk.type === 'text' && chunk.content) {
                     fullContent += chunk.content;
-                    yield chunk.content;
+                    yield chunk;
                 }
                 else if (chunk.type === 'tool_calls' && chunk.toolCalls) {
                     detectedToolCalls = chunk.toolCalls;
+                    // Don't yield the raw tool_calls chunk here — we emit one combined
+                    // chunk after persisting the assistant message so consumers don't
+                    // double-render.
+                }
+                else if (chunk.type === 'thinking') {
+                    yield chunk;
+                }
+                else if (chunk.type === 'usage') {
+                    lastUsage = chunk.usage;
+                    yield chunk;
                 }
             }
             // If we got tool calls, execute them and loop
             if (detectedToolCalls && detectedToolCalls.length > 0) {
-                // Add assistant message with tool calls
+                // Add assistant message with tool calls (append-only, preserves prefix cache)
                 currentMessages.push({
                     role: 'assistant',
                     content: fullContent || '',
                     tool_calls: detectedToolCalls,
                 });
-                // Execute each tool
+                // Execute each tool and emit a single structured tool_calls chunk
+                // describing the dispatch plan. Per-tool results are appended to
+                // currentMessages but NOT yielded as additional chunks — consumers
+                // that want to display result text can introspect tool_calls[*].result
+                // on a synthesized combined chunk, OR we re-emit one tool_calls chunk
+                // at the end with results attached. We choose the simpler approach:
+                // emit ONE tool_calls chunk per iteration with all the calls; results
+                // are surfaced through the next assistant turn's text content.
+                //
+                // v3.0.0 Tool-call Repair (Reasonix P2): on tool failure we APPEND
+                // a `[TOOL_REPAIR]` system message rather than mutating the existing
+                // tool_call message. This preserves the upstream cache prefix —
+                // re-writing an earlier message would shift the prefix by N bytes
+                // and bust the cache for every subsequent round.
                 for (const toolCall of detectedToolCalls) {
                     const tool = this.tools.get(toolCall.function.name);
-                    // Yield structured tool call as JSON line
-                    yield `\n@@TOOL@@${JSON.stringify({ action: 'call', name: toolCall.function.name, args: toolCall.function.arguments })}\n`;
                     if (!tool) {
                         const errMsg = `Tool "${toolCall.function.name}" not found`;
+                        // Repair message — explain the failure and tell the model to
+                        // try a different tool. Cache-safe because we are APPENDING,
+                        // never modifying existing messages.
+                        currentMessages.push({
+                            role: 'system',
+                            content: `[TOOL_REPAIR] Previous tool_call "${toolCall.function.name}" (id=${toolCall.id}) failed: ${errMsg}. Available tools: ${[...this.tools.keys()].join(', ')}.`,
+                        });
                         currentMessages.push({
                             role: 'tool',
                             content: errMsg,
                             tool_call_id: toolCall.id,
                             name: toolCall.function.name,
                         });
-                        yield `@@TOOL@@${JSON.stringify({ action: 'result', error: errMsg })}\n`;
                         continue;
                     }
                     try {
@@ -113,7 +162,13 @@ export class LLMService {
                             tool_call_id: toolCall.id,
                             name: toolCall.function.name,
                         });
-                        yield `@@TOOL@@${JSON.stringify({ action: 'result', output })}\n`;
+                        if (!result.success) {
+                            // Soft failure: tool returned success=false. Same repair pattern.
+                            currentMessages.push({
+                                role: 'system',
+                                content: `[TOOL_REPAIR] Tool "${toolCall.function.name}" returned success=false: ${output}. Consider correcting the arguments and retrying.`,
+                            });
+                        }
                     }
                     catch (error) {
                         const errMsg = `Error: ${error.message}`;
@@ -123,14 +178,27 @@ export class LLMService {
                             tool_call_id: toolCall.id,
                             name: toolCall.function.name,
                         });
-                        yield `@@TOOL@@${JSON.stringify({ action: 'result', error: errMsg })}\n`;
+                        // Hard failure: tool.execute threw. Repair message so the model
+                        // can see the failure next round and adjust (e.g. fix a path
+                        // typo, retry without the optional arg).
+                        currentMessages.push({
+                            role: 'system',
+                            content: `[TOOL_REPAIR] Tool "${toolCall.function.name}" threw an exception: ${errMsg}. Inspect the arguments and retry with a corrected call.`,
+                        });
                     }
                 }
-                yield '\n';
+                // Emit one tool_calls chunk for this iteration. TUI renders this as a
+                // "tool invoked" entry. Per-tool outputs are summarized on the next
+                // assistant turn.
+                yield { type: 'tool_calls', toolCalls: detectedToolCalls };
                 continue;
             }
-            // No tool calls - done
-            return { content: fullContent, role: 'assistant' };
+            // No tool calls - done. Return final response (with usage if we have it).
+            return {
+                content: fullContent,
+                role: 'assistant',
+                usage: lastUsage,
+            };
         }
         return { content: '[Agent loop exceeded maximum iterations]', role: 'assistant' };
     }

package/dist/llm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,OAAO,UAAU;IACb,QAAQ,CAAc;IACtB,KAAK,GAAsB,IAAI,GAAG,EAAE,CAAC;IACrC,MAAM,CAAS;IAEvB,YAAY,QAAqB,EAAE,MAAc;QAC/C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,MAA8C;QAC9D,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,IAAI,aAAa,CAAC;QACtD,MAAM,cAAc,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;QAE/C,MAAM,WAAW,GAAG;YAClB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;YAC3B,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,cAAc,CAAC,YAAY;YAClD,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,cAAc,CAAC,OAAO;YACjD,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,GAAG;YACtC,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI;YACnC,+DAA+D;YAC/D,sEAAsE;YACtE,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAe,EAAE;SAC/E,CAAC;QAEF,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC;QACrC,IAAI,QAAqB,CAAC;QAE1B,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,WAAW;gBACd,QAAQ,GAAG,IAAI,iBAAiB,CAAC,WAAW,CAAC,CAAC;gBAC9C,MAAM;YACR,KAAK,QAAQ;gBACX,QAAQ,GAAG,IAAI,cAAc,CAAC,WAAW,CAAC,CAAC;gBAC3C,MAAM;YACR;gBACE,QAAQ,GAAG,IAAI,cAAc,CAAC,WAAW,CAAC,CAAC;QAC/C,CAAC;QAED,OAAO,IAAI,UAAU,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtD,CAAC;IAED,aAAa,CAAC,KAAa;QACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,eAAe,KAAa,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACxD,SAAS,KAAc,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAE9C,KAAK,CAAC,IAAI,CAAC,QAAuB,EAAE,OAAqB;QACvD,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;QAC/D,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC/F,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,CAAC,UAAU,CACf,QAAuB,EACvB,OAAkD;QAElD,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;QAE/D,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,EAAE,CAAC;QACnD,IAAI,eAAe,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;QACpC,IAAI,UAAU,GAAG,CAAC,CAAC;QACnB,IAAI,SAA4C,CAAC;QAEjD,OAAO,UAAU,GAAG,aAAa,EAAE,CAAC;YAClC,UAAU,EAAE,CAAC;YACb,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;YAC5C,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;YAEvC,IAAI,WAAW,GAAG,EAAE,CAAC;YACrB,IAAI,iBAAyC,CAAC;YAE9C,0EAA0E;YAC1E,0EAA0E;YAC1E,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,eAAe,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAErG,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBACjC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;oBAC3C,WAAW,IAAI,KAAK,CAAC,OAAO,CAAC;oBAC7B,MAAM,KAAK,CAAC;gBACd,CAAC;qBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;oBAC1D,iBAAiB,GAAG,KAAK,CAAC,SAAS,CAAC;oBACpC,mEAAmE;oBACnE,kEAAkE;oBAClE,iBAAiB;gBACnB,CAAC;qBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;oBACrC,MAAM,KAAK,CAAC;gBACd,CAAC;qBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;oBAClC,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC;oBACxB,MAAM,KAAK,CAAC;gBACd,CAAC;YACH,CAAC;YAED,8CAA8C;YAC9C,IAAI,iBAAiB,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtD,8EAA8E;gBAC9E,eAAe,CAAC,IAAI,CAAC;oBACnB,IAAI,EAAE,WAAW;oBACjB,OAAO,EAAE,WAAW,IAAI,EAAE;oBAC1B,UAAU,EAAE,iBAAiB;iBAC9B,CAAC,CAAC;gBAEH,kEAAkE;gBAClE,iEAAiE;gBACjE,mEAAmE;gBACnE,uEAAuE;gBACvE,sEAAsE;gBACtE,oEAAoE;gBACpE,sEAAsE;gBACtE,+DAA+D;gBAC/D,EAAE;gBACF,mEAAmE;gBACnE,qEAAqE;gBACrE,gEAAgE;gBAChE,kEAAkE;gBAClE,iDAAiD;gBACjD,KAAK,MAAM,QAAQ,IAAI,iBAAiB,EAAE,CAAC;oBACzC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;oBAEpD,IAAI,CAAC,IAAI,EAAE,CAAC;wBACV,MAAM,MAAM,GAAG,SAAS,QAAQ,CAAC,QAAQ,CAAC,IAAI,aAAa,CAAC;wBAC5D,6DAA6D;wBAC7D,6DAA6D;wBAC7D,qCAAqC;wBACrC,eAAe,CAAC,IAAI,CAAC;4BACnB,IAAI,EAAE,QAAQ;4BACd,OAAO,EAAE,qCAAqC,QAAQ,CAAC,QAAQ,CAAC,IAAI,SAAS,QAAQ,CAAC,EAAE,aAAa,MAAM,sBAAsB,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;yBACtK,CAAC,CAAC;wBACH,eAAe,CAAC,IAAI,CAAC;4BACnB,IAAI,EAAE,MAAM;4BACZ,OAAO,EAAE,MAAM;4BACf,YAAY,EAAE,QAAQ,CAAC,EAAE;4BACzB,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI;yBAC7B,CAAC,CAAC;wBACH,SAAS;oBACX,CAAC;oBAED,IAAI,CAAC;wBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;wBAC/D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;wBAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,aAAa,CAAC,CAAC;wBAEjH,eAAe,CAAC,IAAI,CAAC;4BACnB,IAAI,EAAE,MAAM;4BACZ,OAAO,EAAE,MAAM;4BACf,YAAY,EAAE,QAAQ,CAAC,EAAE;4BACzB,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI;yBAC7B,CAAC,CAAC;wBAEH,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;4BACpB,kEAAkE;4BAClE,eAAe,CAAC,IAAI,CAAC;gCACnB,IAAI,EAAE,QAAQ;gCACd,OAAO,EAAE,uBAAuB,QAAQ,CAAC,QAAQ,CAAC,IAAI,6BAA6B,MAAM,mDAAmD;6BAC7I,CAAC,CAAC;wBACL,CAAC;oBACH,CAAC;oBAAC,OAAO,KAAU,EAAE,CAAC;wBACpB,MAAM,MAAM,GAAG,UAAU,KAAK,CAAC,OAAO,EAAE,CAAC;wBACzC,eAAe,CAAC,IAAI,CAAC;4BACnB,IAAI,EAAE,MAAM;4BACZ,OAAO,EAAE,MAAM;4BACf,YAAY,EAAE,QAAQ,CAAC,EAAE;4BACzB,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI;yBAC7B,CAAC,CAAC;wBACH,gEAAgE;wBAChE,6DAA6D;wBAC7D,yCAAyC;wBACzC,eAAe,CAAC,IAAI,CAAC;4BACnB,IAAI,EAAE,QAAQ;4BACd,OAAO,EAAE,uBAAuB,QAAQ,CAAC,QAAQ,CAAC,IAAI,yBAAyB,MAAM,0DAA0D;yBAChJ,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC;gBAED,sEAAsE;gBACtE,oEAAoE;gBACpE,kBAAkB;gBAClB,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC;gBAC3D,SAAS;YACX,CAAC;YAED,0EAA0E;YAC1E,OAAO;gBACL,OAAO,EAAE,WAAW;gBACpB,IAAI,EAAE,WAAW;gBACjB,KAAK,EAAE,SAAS;aACjB,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,0CAA0C,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACpF,CAAC;IAEO,YAAY,CAAC,IAAY;QAC/B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;YACrC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAC;YACpC,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE;gBAC5B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBAChF,OAAO,GAAG,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;YACxC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7D,CAAC;IACH,CAAC;IAEO,eAAe;QACrB,OAAO;YACL,wBAAwB;YACxB,EAAE;YACF,mBAAmB;YACnB,EAAE;YACF,UAAU;YACV,uCAAuC;YACvC,kCAAkC;YAClC,oCAAoC;SACrC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;CACF;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/llm/openai.d.ts

@@ -2,15 +2,20 @@
  * OpenAI-compatible Provider
  * Works with: OpenAI, SiliconFlow, DeepSeek, Kimi, Zhipu, MiniMax, Baichuan, Stepfun, Doubao, Ollama, ERNIE
  * Also works with any OpenAI-compatible relay station (中转站)
+ *
+ * v3.0.0+: caching-friendly wire format
+ *   - StreamChunk is now imported from ../types (single source of truth)
+ *   - buildRequest uses stableStringify so that the bytes sent are byte-equal
+ *     between requests with the same logical payload (required for DeepSeek
+ *     automatic prefix-cache hit)
+ *   - cache_control on individual ChatMessage is forwarded (Anthropic-style
+ *     markers are no-ops on OpenAI-compatible APIs but harmless)
+ *   - chatStream yields a final { type: 'usage' } chunk if the upstream
+ *     returned usage info (stream_options.include_usage already requested)
  */
-import type { ChatMessage, ChatResponse, ChatOptions, ToolCall } from '../types.js';
+import type { ChatMessage, ChatResponse, ChatOptions, StreamChunk } from '../types.js';
 import type { Tool } from '../tools/types.js';
 import type { LLMProvider, ProviderConfig } from './provider.js';
-export interface StreamChunk {
-    type: 'text' | 'tool_calls';
-    content?: string;
-    toolCalls?: ToolCall[];
-}
 export declare class OpenAIProvider implements LLMProvider {
     readonly name = "openai";
     protected config: ProviderConfig;
@@ -19,12 +24,27 @@ export declare class OpenAIProvider implements LLMProvider {
     chat(messages: ChatMessage[], options?: ChatOptions, tools?: Tool[]): Promise<ChatResponse>;
     chatStream(messages: ChatMessage[], options?: ChatOptions, tools?: Tool[]): AsyncGenerator<StreamChunk, ChatResponse>;
     /**
-     * Build the request body for OpenAI-compatible API
+     * Build the request body for OpenAI-compatible API.
+     *
+     * Why stableStringify matters: DeepSeek (and most OpenAI-compatible APIs)
+     * perform automatic prefix cache lookup by byte-level hash of the request
+     * payload. If the JSON we send today differs from yesterday's by even one
+     * reordered key, the cache misses. Insertion-order stability is good enough
+     * when the same code path runs every time, but we now use stableStringify
+     * as a belt-and-suspenders guarantee against accidental key reordering from
+     * future refactors (spread / Object.fromEntries / map merging).
      */
     protected buildRequest(messages: ChatMessage[], stream: boolean, options?: ChatOptions, tools?: Tool[]): any;
     /**
-     * Execute the HTTP request
+     * Execute the HTTP request. Serializes via stableStringify so the byte
+     * sequence is deterministic across requests.
      */
     protected doRequest(body: any): Promise<Response>;
+    /**
+     * Map upstream usage JSON to the canonical Usage shape. Different providers
+     * attach different cache-related fields; we pass everything through so the
+     * cache stats layer can interpret per-provider.
+     */
+    protected normalizeUsage(raw: any): ChatResponse['usage'];
 }
 //# sourceMappingURL=openai.d.ts.map

package/dist/llm/openai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/llm/openai.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEjE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;CACxB;AAED,qBAAa,cAAe,YAAW,WAAW;IAChD,QAAQ,CAAC,IAAI,YAAY;IACzB,SAAS,CAAC,MAAM,EAAE,cAAc,CAAC;gBAErB,MAAM,EAAE,cAAc;IAIlC,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,GAAG,EAAE;IAiB1B,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAkB1F,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,cAAc,CAAC,WAAW,EAAE,YAAY,CAAC;IAsF5H;;OAEG;IACH,SAAS,CAAC,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE;IAwBtG;;OAEG;cACa,SAAS,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC;CAoBxD"}
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/llm/openai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAY,WAAW,EAAE,MAAM,aAAa,CAAC;AACjG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGjE,qBAAa,cAAe,YAAW,WAAW;IAChD,QAAQ,CAAC,IAAI,YAAY;IACzB,SAAS,CAAC,MAAM,EAAE,cAAc,CAAC;gBAErB,MAAM,EAAE,cAAc;IAIlC,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,GAAG,EAAE;IAiB1B,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAc1F,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,cAAc,CAAC,WAAW,EAAE,YAAY,CAAC;IAoG5H;;;;;;;;;;OAUG;IACH,SAAS,CAAC,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE;IA4BtG;;;OAGG;cACa,SAAS,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC;IAqBvD;;;;OAIG;IACH,SAAS,CAAC,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC;CAa1D"}

package/dist/llm/openai.js

@@ -2,7 +2,18 @@
  * OpenAI-compatible Provider
  * Works with: OpenAI, SiliconFlow, DeepSeek, Kimi, Zhipu, MiniMax, Baichuan, Stepfun, Doubao, Ollama, ERNIE
  * Also works with any OpenAI-compatible relay station (中转站)
+ *
+ * v3.0.0+: caching-friendly wire format
+ *   - StreamChunk is now imported from ../types (single source of truth)
+ *   - buildRequest uses stableStringify so that the bytes sent are byte-equal
+ *     between requests with the same logical payload (required for DeepSeek
+ *     automatic prefix-cache hit)
+ *   - cache_control on individual ChatMessage is forwarded (Anthropic-style
+ *     markers are no-ops on OpenAI-compatible APIs but harmless)
+ *   - chatStream yields a final { type: 'usage' } chunk if the upstream
+ *     returned usage info (stream_options.include_usage already requested)
  */
+import { stableStringify } from '../utils/stableStringify.js';
 export class OpenAIProvider {
     name = 'openai';
     config;
@@ -31,11 +42,7 @@ export class OpenAIProvider {
         return {
             content: choice?.message?.content || '',
             role: 'assistant',
-            usage: data.usage ? {
-                prompt_tokens: data.usage.prompt_tokens || 0,
-                completion_tokens: data.usage.completion_tokens || 0,
-                total_tokens: data.usage.total_tokens || 0,
-            } : undefined,
+            usage: data.usage ? this.normalizeUsage(data.usage) : undefined,
             tool_calls: choice?.message?.tool_calls,
         };
     }
@@ -52,6 +59,9 @@ export class OpenAIProvider {
         let buffer = '';
         // Accumulate streaming tool call chunks
         const toolCallBuffers = new Map();
+        // Some providers attach usage only on the last chunk (DeepSeek / OpenAI with
+        // stream_options.include_usage). We capture it here and yield at the end.
+        let capturedUsage;
         try {
             while (true) {
                 const { done, value } = await reader.read();
@@ -92,6 +102,10 @@ export class OpenAIProvider {
                                     buf.arguments += tc.function.arguments;
                             }
                         }
+                        // DeepSeek/OpenAI stream-end usage (only present on the last chunk)
+                        if (data.usage) {
+                            capturedUsage = this.normalizeUsage(data.usage);
+                        }
                     }
                     catch {
                         // Skip invalid JSON lines
@@ -116,24 +130,41 @@ export class OpenAIProvider {
         if (toolCalls.length > 0) {
             yield { type: 'tool_calls', toolCalls };
         }
+        // Yield captured usage so TUI / cache stats can observe cache hits
+        if (capturedUsage) {
+            yield { type: 'usage', usage: capturedUsage };
+        }
         return {
             content: fullContent,
             role: 'assistant',
+            usage: capturedUsage,
             tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
         };
     }
     /**
-     * Build the request body for OpenAI-compatible API
+     * Build the request body for OpenAI-compatible API.
+     *
+     * Why stableStringify matters: DeepSeek (and most OpenAI-compatible APIs)
+     * perform automatic prefix cache lookup by byte-level hash of the request
+     * payload. If the JSON we send today differs from yesterday's by even one
+     * reordered key, the cache misses. Insertion-order stability is good enough
+     * when the same code path runs every time, but we now use stableStringify
+     * as a belt-and-suspenders guarantee against accidental key reordering from
+     * future refactors (spread / Object.fromEntries / map merging).
      */
     buildRequest(messages, stream, options, tools) {
         const body = {
             model: this.config.model,
             messages: messages.map(m => ({
                 role: m.role,
+                // content is string | ContentBlock[]. OpenAI wire format accepts both:
+                // - string for plain text messages
+                // - array of {type,text} or {type,image_url} blocks for multimodal
                 content: m.content,
                 ...(m.name && { name: m.name }),
                 ...(m.tool_call_id && { tool_call_id: m.tool_call_id }),
                 ...(m.tool_calls && { tool_calls: m.tool_calls }),
+                ...(m.cache_control && { cache_control: m.cache_control }),
             })),
             temperature: options?.temperature ?? this.config.temperature,
             max_tokens: options?.maxTokens ?? this.config.maxTokens,
@@ -147,7 +178,8 @@ export class OpenAIProvider {
         return body;
     }
     /**
-     * Execute the HTTP request
+     * Execute the HTTP request. Serializes via stableStringify so the byte
+     * sequence is deterministic across requests.
      */
     async doRequest(body) {
         const url = `${this.config.baseUrl}/chat/completions`;
@@ -160,7 +192,7 @@ export class OpenAIProvider {
                     'Content-Type': 'application/json',
                     'Authorization': `Bearer ${this.config.apiKey}`,
                 },
-                body: JSON.stringify(body),
+                body: stableStringify(body),
                 signal: controller.signal,
             });
             return response;
@@ -169,5 +201,23 @@ export class OpenAIProvider {
             clearTimeout(timeout);
         }
     }
+    /**
+     * Map upstream usage JSON to the canonical Usage shape. Different providers
+     * attach different cache-related fields; we pass everything through so the
+     * cache stats layer can interpret per-provider.
+     */
+    normalizeUsage(raw) {
+        return {
+            prompt_tokens: raw.prompt_tokens || 0,
+            completion_tokens: raw.completion_tokens || 0,
+            total_tokens: raw.total_tokens || 0,
+            // DeepSeek automatic prefix cache fields
+            prompt_cache_hit_tokens: raw.prompt_cache_hit_tokens,
+            prompt_cache_miss_tokens: raw.prompt_cache_miss_tokens,
+            // Anthropic prompt cache fields (passed through if relay forwards them)
+            cache_creation_input_tokens: raw.cache_creation_input_tokens,
+            cache_read_input_tokens: raw.cache_read_input_tokens,
+        };
+    }
 }
 //# sourceMappingURL=openai.js.map

package/dist/llm/openai.js.map

@@ -1 +1 @@
-{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/llm/openai.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/llm/openai.ts"],"names":[],"mappings":"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"}

package/dist/llm/provider.d.ts

@@ -1,19 +1,36 @@
 /**
  * Abstract LLM Provider interface
- * All providers implement this interface
+ * All providers implement this interface.
+ *
+ * v3.0.0+: StreamChunk is now imported from the shared types module so that
+ * TUI / session / cache layers can consume it uniformly. Providers no longer
+ * carry their own definition; see src/types.ts for the union (text/tool_calls/
+ * thinking/usage). The previous local 'text' | 'tool_calls' shape was kept as
+ * a structural type alias for backward compatibility with existing call sites
+ * that destructure by .type only.
  */
-import type { ChatMessage, ChatResponse, ChatOptions, ToolCall } from '../types.js';
+import type { ChatMessage, ChatResponse, ChatOptions, StreamChunk as SharedStreamChunk } from '../types.js';
 import type { Tool } from '../tools/types.js';
-export interface StreamChunk {
-    type: 'text' | 'tool_calls';
-    content?: string;
-    toolCalls?: ToolCall[];
-}
+/**
+ * Re-export of the structured streaming chunk. Now structurally compatible
+ * with the old { type, content?, toolCalls? } shape — callers that previously
+ * destructured chunk.type and chunk.content / chunk.toolCalls still work, and
+ * new variants ('thinking', 'usage') are opt-in.
+ */
+export type StreamChunk = SharedStreamChunk;
 export interface LLMProvider {
     readonly name: string;
     /** Non-streaming chat with optional tools */
     chat(messages: ChatMessage[], options?: ChatOptions, tools?: Tool[]): Promise<ChatResponse>;
-    /** Streaming chat with optional tools - yields StreamChunks */
+    /**
+     * Streaming chat with optional tools.
+     * Yields structured StreamChunks:
+     *   { type: 'text',       content: string }
+     *   { type: 'tool_calls', toolCalls: ToolCall[] }
+     *   { type: 'thinking',   content: string }
+     *   { type: 'usage',      usage: Usage }
+     * Returns the final ChatResponse (with usage) when the stream completes.
+     */
     chatStream(messages: ChatMessage[], options?: ChatOptions, tools?: Tool[]): AsyncGenerator<StreamChunk, ChatResponse>;
     /** Convert Tool[] to provider-specific format */
     buildTools(tools: Tool[]): any[];
@@ -24,5 +41,20 @@ export interface ProviderConfig {
     baseUrl: string;
     temperature: number;
     maxTokens: number;
+    /**
+     * Optional cache control policy. When omitted, providers fall back to their
+     * default behavior (Anthropic: explicit cache_control markers; OpenAI / Gemini
+     * / DeepSeek: automatic prefix cache, no markers needed).
+     */
+    cache?: {
+        enabled: boolean;
+        ttl?: '5m' | '1h';
+        /**
+         * 'auto'   — provider default (Anthropic: explicit, OpenAI/DeepSeek: auto)
+         * 'manual' — always emit cache_control markers regardless of provider
+         * 'off'    — never emit markers (force disable, useful for benchmarking)
+         */
+        strategy?: 'auto' | 'manual' | 'off';
+    };
 }
 //# sourceMappingURL=provider.d.ts.map

package/dist/llm/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,6CAA6C;IAC7C,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAE5F,+DAA+D;IAC/D,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,cAAc,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAEtH,iDAAiD;IACjD,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,GAAG,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,IAAI,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC5G,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAE5C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,6CAA6C;IAC7C,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAE5F;;;;;;;;OAQG;IACH,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,cAAc,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAEtH,iDAAiD;IACjD,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,GAAG,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,OAAO,CAAC;QACjB,GAAG,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;QAClB;;;;WAIG;QACH,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;KACtC,CAAC;CACH"}

package/dist/llm/provider.js

@@ -1,6 +1,13 @@
 /**
  * Abstract LLM Provider interface
- * All providers implement this interface
+ * All providers implement this interface.
+ *
+ * v3.0.0+: StreamChunk is now imported from the shared types module so that
+ * TUI / session / cache layers can consume it uniformly. Providers no longer
+ * carry their own definition; see src/types.ts for the union (text/tool_calls/
+ * thinking/usage). The previous local 'text' | 'tool_calls' shape was kept as
+ * a structural type alias for backward compatibility with existing call sites
+ * that destructure by .type only.
  */
 export {};
 //# sourceMappingURL=provider.js.map

package/dist/llm/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AAAA;;;GAGG"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/prompts/index.d.ts

@@ -10,10 +10,42 @@ export interface SystemPromptConfig {
     date?: Date;
     skillsPrompt?: string;
 }
+/**
+ * v3.0.0: a single named fragment of the system prompt. The provider layer
+ * attaches cache_control markers to volatile=false segments (Anthropic) and
+ * the fingerprint module hashes only the non-volatile portion.
+ */
+export interface SystemSegment {
+    /** Stable identifier, used in fingerprints and logging. */
+    name: string;
+    /** Rendered text content. May be empty string if the section was a no-op. */
+    content: string;
+    /**
+     * volatile=false: content never changes between requests within a session.
+     * volatile=true:  content may change (NWT events, current time).
+     */
+    volatile: boolean;
+}
 export declare class SystemPromptBuilder {
     private config;
     constructor(config?: SystemPromptConfig);
     build(): string;
+    /**
+     * v3.0.0: build the system prompt as named segments instead of a flat
+     * string. The provider layer (Anthropic) can attach cache_control markers
+     * to the segments it caches, and the fingerprint module can hash the
+     * static portion to detect when the immutable prefix changed.
+     *
+     * Ordering rule (Reasonix-style): immutable prefix first, volatile tail
+     * last. NWT history and Date move to the tail because both can change
+     * between rounds (Date: every build; NWT: when a new event is logged).
+     * Keeping them out of the prefix means the upstream cache keeps its
+     * prefix checkpoint stable across those changes.
+     *
+     * Segments with empty content are filtered out — they neither contribute
+     * to the string output nor to any cache fingerprint.
+     */
+    buildSegments(): SystemSegment[];
     private buildIdentity;
     private buildToolInstructions;
     private buildEnvironment;

package/dist/prompts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IAC3C,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAA+B;gBAEjC,MAAM,GAAE,kBAAuB;IAW3C,KAAK,IAAI,MAAM;IAcf,OAAO,CAAC,aAAa;IA0CrB,OAAO,CAAC,qBAAqB;IAc7B,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,mBAAmB;IAU3B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAqDhC;;OAEG;IACH,OAAO,CAAC,eAAe;IA+BvB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,aAAa;IAMrB,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAC7B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IACzB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,IAAI;CACzD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IAC3C,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAA+B;gBAEjC,MAAM,GAAE,kBAAuB;IAW3C,KAAK,IAAI,MAAM;IAOf;;;;;;;;;;;;;;OAcG;IACH,aAAa,IAAI,aAAa,EAAE;IAehC,OAAO,CAAC,aAAa;IA0CrB,OAAO,CAAC,qBAAqB;IAc7B,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,mBAAmB;IAU3B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAqDhC;;OAEG;IACH,OAAO,CAAC,eAAe;IA+BvB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,aAAa;IAMrB,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAC7B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IACzB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,IAAI;CACzD"}