@x-code-cli/core 0.1.11 → 0.2.0

package/dist/tools/enter-plan-mode.js

@@ -0,0 +1,120 @@
+// @x-code-cli/core — enterPlanMode tool (mode switch, no execute — handled in agent loop)
+import { tool } from 'ai';
+import { z } from 'zod';
+/** The tool description below is the heart of plan-mode auto-trigger
+ *  behavior — it's what the model reads in the tool list and uses to
+ *  decide whether to recommend plan mode. Ported (with naming
+ *  adjustments for our tool surface) from Claude Code's
+ *  `EnterPlanModeTool/prompt.ts` external-user prompt
+ *  (`/d/res/claude-code/src/tools/EnterPlanModeTool/prompt.ts:16-99`).
+ *
+ *  WHY THIS IS LONG: a one-line description ("use for complex tasks")
+ *  produces a model that almost never calls the tool — it has no
+ *  concrete trigger pattern to match against the user's request. CC's
+ *  prompt deliberately includes 7 numbered criteria, multiple worked
+ *  examples per criterion, and an explicit "PREFER plan mode unless
+ *  simple" anchor — that's what gets the model to actually recommend
+ *  plan mode for refactors, new features, architectural decisions,
+ *  etc. The token cost (~600 tokens in tool list each turn) is what
+ *  buys the auto-trigger behavior; without it plan mode is dead UX.
+ *
+ *  No `execute` field — the side-effect (asking the user to confirm,
+ *  mutating LoopState.permissionMode, invalidating the system-prompt
+ *  cache) is handled manually in `processToolCalls`. Same pattern as
+ *  `askUser`. */
+export const enterPlanMode = tool({
+    description: `Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.
+
+## When to Use This Tool
+
+**Prefer using enterPlanMode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:
+
+1. **New Feature Implementation**: Adding meaningful new functionality
+   - Example: "Add a logout button" - where should it go? What should happen on click?
+   - Example: "Add form validation" - what rules? What error messages?
+
+2. **Multiple Valid Approaches**: The task can be solved in several different ways
+   - Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc.
+   - Example: "Improve performance" - many optimization strategies possible
+
+3. **Code Modifications**: Changes that affect existing behavior or structure
+   - Example: "Update the login flow" - what exactly should change?
+   - Example: "Refactor this component" - what's the target architecture?
+
+4. **Architectural Decisions**: The task requires choosing between patterns or technologies
+   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
+   - Example: "Implement state management" - Redux vs Context vs custom solution
+
+5. **Multi-File Changes**: The task will likely touch more than 2-3 files
+   - Example: "Refactor the authentication system"
+   - Example: "Add a new API endpoint with tests"
+
+6. **Unclear Requirements**: You need to explore before understanding the full scope
+   - Example: "Make the app faster" - need to profile and identify bottlenecks
+   - Example: "Fix the bug in checkout" - need to investigate root cause
+
+7. **User Preferences Matter**: The implementation could reasonably go multiple ways
+   - If you would use askUser to clarify the approach, use enterPlanMode instead
+   - Plan mode lets you explore first, then present options with context
+
+## When NOT to Use This Tool
+
+Only skip enterPlanMode for simple tasks:
+- Single-line or few-line fixes (typos, obvious bugs, small tweaks)
+- Adding a single function with clear requirements
+- Tasks where the user has given very specific, detailed instructions
+- Pure research / "what does X do" questions — just answer them directly
+
+## What Happens in Plan Mode
+
+In plan mode, you'll:
+1. Thoroughly explore the codebase using readFile, glob, grep, and listDir
+2. Understand existing patterns and architecture
+3. Design an implementation approach
+4. Use askUser to clarify approaches with the user when needed
+5. Write the plan incrementally to a session-scoped plan file
+6. Exit plan mode with exitPlanMode when ready to implement
+
+## Examples
+
+### GOOD - Use enterPlanMode:
+User: "Add user authentication to the app"
+- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)
+
+User: "Optimize the database queries"
+- Multiple approaches possible, need to profile first, significant impact
+
+User: "Implement dark mode"
+- Architectural decision on theme system, affects many components
+
+User: "Add a delete button to the user profile"
+- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates
+
+User: "Update the error handling in the API"
+- Affects multiple files, user should approve the approach
+
+### BAD - Don't use enterPlanMode:
+User: "Fix the typo in the README"
+- Straightforward, no planning needed
+
+User: "Add a console.log to debug this function"
+- Simple, obvious implementation
+
+User: "What files handle routing?"
+- Research / Q&A task, not implementation — just answer
+
+## Important Notes
+
+- This tool REQUIRES user approval — they must consent to entering plan mode (an approval dialog appears).
+- If unsure whether to use it, err on the side of planning — it's better to get alignment upfront than to redo work.
+- Do not call enterPlanMode if you are already in plan mode (check the system prompt; if you see plan-mode instructions you are already in it).`,
+    inputSchema: z.object({
+        topic: z
+            .string()
+            .min(1)
+            .max(60)
+            .optional()
+            .describe('STRONGLY RECOMMENDED. A 3-5 word English filename slug summarizing the user\'s task. Lowercase, hyphen-separated, no spaces or special chars. The plan file is named `<topic>-<YYYYMMDD-HHMMSS>.md` so this makes the file identifiable in `ls .x-code/plans/`. Translate non-English requests into English keywords (e.g. user asks "重构这个项目" → topic: "refactor-x-code-cli"; user asks "加 OAuth 登录" → topic: "add-oauth-login"). Omit only when you genuinely cannot summarize — the file then falls back to timestamp-only naming.'),
+    }),
+});
+//# sourceMappingURL=enter-plan-mode.js.map

package/dist/tools/enter-plan-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enter-plan-mode.js","sourceRoot":"","sources":["../../src/tools/enter-plan-mode.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAEzB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;;;;;;;;;;iBAoBiB;AACjB,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gJAoFiI;IAC9I,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,EAAE,CAAC;aACP,QAAQ,EAAE;aACV,QAAQ,CACP,sgBAAsgB,CACvgB;KACJ,CAAC;CACH,CAAC,CAAA"}

package/dist/tools/exit-plan-mode.d.ts

@@ -0,0 +1,13 @@
+/** Present the plan to the user for approval. The user sees a Yes/No
+ *  dialog with the plan body inline; on Yes, the session leaves plan mode
+ *  and the next turn can write code; on No, the session stays in plan
+ *  mode and the model is told to revise.
+ *
+ *  No `execute` field — the dispatch path in `processToolCalls` reads the
+ *  plan file, calls `callbacks.onPlanApprovalRequest(planText)`, and
+ *  feeds the verdict back as a synthetic tool result so the model knows
+ *  whether to proceed or iterate. */
+export declare const exitPlanMode: import("ai").Tool<{
+    plan?: string | undefined;
+}, never>;
+//# sourceMappingURL=exit-plan-mode.d.ts.map

package/dist/tools/exit-plan-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-plan-mode.d.ts","sourceRoot":"","sources":["../../src/tools/exit-plan-mode.ts"],"names":[],"mappings":"AAKA;;;;;;;;qCAQqC;AACrC,eAAO,MAAM,YAAY;;SAWvB,CAAA"}

package/dist/tools/exit-plan-mode.js

@@ -0,0 +1,22 @@
+// @x-code-cli/core — exitPlanMode tool (user-approval gate, no execute — handled in agent loop)
+import { tool } from 'ai';
+import { z } from 'zod';
+/** Present the plan to the user for approval. The user sees a Yes/No
+ *  dialog with the plan body inline; on Yes, the session leaves plan mode
+ *  and the next turn can write code; on No, the session stays in plan
+ *  mode and the model is told to revise.
+ *
+ *  No `execute` field — the dispatch path in `processToolCalls` reads the
+ *  plan file, calls `callbacks.onPlanApprovalRequest(planText)`, and
+ *  feeds the verdict back as a synthetic tool result so the model knows
+ *  whether to proceed or iterate. */
+export const exitPlanMode = tool({
+    description: 'Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval. This tool reads the plan from the file you wrote during planning — pass an optional `plan` parameter only if you want to override what is in the file. The user sees the plan content in an approval dialog and chooses Yes/No. The model cannot leave plan mode without user approval; if rejected, revise the plan file (using edit) and call this again. Do NOT use this for research / Q&A — only when the user has asked you to implement something and you have a complete plan written to the plan file. Do NOT use askUser to ask "is this plan okay?" — exitPlanMode is the only correct way to request plan approval.',
+    inputSchema: z.object({
+        plan: z
+            .string()
+            .optional()
+            .describe('Optional override for the plan body. By default the plan body comes from the plan file you wrote during planning — only pass this argument if you want to use different content (rare).'),
+    }),
+});
+//# sourceMappingURL=exit-plan-mode.js.map

package/dist/tools/exit-plan-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-plan-mode.js","sourceRoot":"","sources":["../../src/tools/exit-plan-mode.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAEzB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;qCAQqC;AACrC,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC;IAC/B,WAAW,EACT,+tBAA+tB;IACjuB,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,yLAAyL,CAC1L;KACJ,CAAC;CACH,CAAC,CAAA"}

package/dist/tools/grep.d.ts

@@ -1,7 +1,7 @@
 export declare const grep: import("ai").Tool<{
     pattern: string;
-    path?: string | undefined;
     glob?: string | undefined;
+    path?: string | undefined;
     maxResults?: number | undefined;
 }, string>;
 //# sourceMappingURL=grep.d.ts.map

package/dist/tools/index.d.ts

@@ -1,11 +1,14 @@
 import { askUser } from './ask-user.js';
 import { edit } from './edit.js';
+import { enterPlanMode } from './enter-plan-mode.js';
+import { exitPlanMode } from './exit-plan-mode.js';
 import { glob } from './glob.js';
 import { grep } from './grep.js';
 import { listDir } from './list-dir.js';
 import { readFile } from './read-file.js';
 import { saveKnowledge } from './save-knowledge.js';
 import { shell } from './shell.js';
+import { todoWrite } from './todo-write.js';
 import { webFetch } from './web-fetch.js';
 import { webSearch } from './web-search.js';
 import { writeFile } from './write-file.js';
@@ -63,8 +66,8 @@ export declare const toolRegistry: {
     }, string>;
     grep: import("ai").Tool<{
         pattern: string;
-        path?: string | undefined;
         glob?: string | undefined;
+        path?: string | undefined;
         maxResults?: number | undefined;
     }, string>;
     listDir: import("ai").Tool<{
@@ -86,14 +89,27 @@ export declare const toolRegistry: {
         question: string;
     }, never>;
     saveKnowledge: import("ai").Tool<{
-        category: "user" | "feedback" | "project" | "reference";
+        category: "project" | "user" | "feedback" | "reference";
         action: "add" | "delete";
         key: string;
         fact: string;
-        scope: "project" | "global";
+        scope: "global" | "project";
     }, string>;
+    enterPlanMode: import("ai").Tool<{
+        topic?: string | undefined;
+    }, never>;
+    exitPlanMode: import("ai").Tool<{
+        plan?: string | undefined;
+    }, never>;
+    todoWrite: import("ai").Tool<{
+        todos: {
+            content?: string | undefined;
+            status?: "pending" | "in_progress" | "completed" | undefined;
+            activeForm?: string | undefined;
+        }[];
+    }, never>;
 };
-export { readFile, writeFile, edit, shell, glob, grep, listDir, webSearch, webFetch, askUser, saveKnowledge, };
+export { readFile, writeFile, edit, shell, glob, grep, listDir, webSearch, webFetch, askUser, saveKnowledge, enterPlanMode, exitPlanMode, todoWrite, };
 export { MAX_TOOL_RESULT_LINES, MAX_TOOL_RESULT_BYTES, MAX_AGGREGATE_TOOL_RESULT_BYTES, truncateToolResult, } from './truncate.js';
 export type { TruncateOptions } from './truncate.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAYxB,CAAA;AAED,OAAO,EACL,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,IAAI,EACJ,OAAO,EACP,SAAS,EACT,QAAQ,EACR,OAAO,EACP,aAAa,GACd,CAAA;AAED,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,+BAA+B,EAC/B,kBAAkB,GACnB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAexB,CAAA;AAED,OAAO,EACL,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,IAAI,EACJ,OAAO,EACP,SAAS,EACT,QAAQ,EACR,OAAO,EACP,aAAa,EACb,aAAa,EACb,YAAY,EACZ,SAAS,GACV,CAAA;AAED,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,+BAA+B,EAC/B,kBAAkB,GACnB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA"}

package/dist/tools/index.js

@@ -1,12 +1,15 @@
 // @x-code-cli/core — Tool registry (unified export)
 import { askUser } from './ask-user.js';
 import { edit } from './edit.js';
+import { enterPlanMode } from './enter-plan-mode.js';
+import { exitPlanMode } from './exit-plan-mode.js';
 import { glob } from './glob.js';
 import { grep } from './grep.js';
 import { listDir } from './list-dir.js';
 import { readFile } from './read-file.js';
 import { saveKnowledge } from './save-knowledge.js';
 import { shell } from './shell.js';
+import { todoWrite } from './todo-write.js';
 import { webFetch } from './web-fetch.js';
 import { webSearch } from './web-search.js';
 import { writeFile } from './write-file.js';
@@ -22,7 +25,10 @@ export const toolRegistry = {
     webFetch,
     askUser,
     saveKnowledge,
+    enterPlanMode,
+    exitPlanMode,
+    todoWrite,
 };
-export { readFile, writeFile, edit, shell, glob, grep, listDir, webSearch, webFetch, askUser, saveKnowledge, };
+export { readFile, writeFile, edit, shell, glob, grep, listDir, webSearch, webFetch, askUser, saveKnowledge, enterPlanMode, exitPlanMode, todoWrite, };
 export { MAX_TOOL_RESULT_LINES, MAX_TOOL_RESULT_BYTES, MAX_AGGREGATE_TOOL_RESULT_BYTES, truncateToolResult, } from './truncate.js';
 //# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,SAAS;IACT,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,IAAI;IACJ,OAAO;IACP,SAAS;IACT,QAAQ;IACR,OAAO;IACP,aAAa;CACd,CAAA;AAED,OAAO,EACL,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,IAAI,EACJ,OAAO,EACP,SAAS,EACT,QAAQ,EACR,OAAO,EACP,aAAa,GACd,CAAA;AAED,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,+BAA+B,EAC/B,kBAAkB,GACnB,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,SAAS;IACT,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,IAAI;IACJ,OAAO;IACP,SAAS;IACT,QAAQ;IACR,OAAO;IACP,aAAa;IACb,aAAa;IACb,YAAY;IACZ,SAAS;CACV,CAAA;AAED,OAAO,EACL,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,IAAI,EACJ,OAAO,EACP,SAAS,EACT,QAAQ,EACR,OAAO,EACP,aAAa,EACb,aAAa,EACb,YAAY,EACZ,SAAS,GACV,CAAA;AAED,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,+BAA+B,EAC/B,kBAAkB,GACnB,MAAM,eAAe,CAAA"}

package/dist/tools/save-knowledge.d.ts

@@ -1,8 +1,8 @@
 export declare const saveKnowledge: import("ai").Tool<{
-    category: "user" | "feedback" | "project" | "reference";
+    category: "project" | "user" | "feedback" | "reference";
     action: "add" | "delete";
     key: string;
     fact: string;
-    scope: "project" | "global";
+    scope: "global" | "project";
 }, string>;
 //# sourceMappingURL=save-knowledge.d.ts.map

package/dist/tools/shell-provider.d.ts

@@ -4,6 +4,10 @@ export interface ShellSpawnOptions {
     timeout: number;
     env?: NodeJS.ProcessEnv;
     cwd?: string;
+    /** When this signal aborts, execa kills the child process tree. Used to
+     *  honor user Esc / Ctrl+C cancellation mid-command without waiting for
+     *  the timeout. */
+    signal?: AbortSignal;
 }
 export interface ShellProvider {
     type: ShellType;

package/dist/tools/shell-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shell-provider.d.ts","sourceRoot":"","sources":["../../src/tools/shell-provider.ts"],"names":[],"mappings":"AAMA,OAAO,EAAS,KAAK,aAAa,EAAE,MAAM,OAAO,CAAA;AAGjD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,YAAY,CAAA;AAErD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAA;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAAA;CAC/D;AA6DD,wBAAgB,gBAAgB,IAAI,aAAa,CAYhD"}
+{"version":3,"file":"shell-provider.d.ts","sourceRoot":"","sources":["../../src/tools/shell-provider.ts"],"names":[],"mappings":"AAMA,OAAO,EAAS,KAAK,aAAa,EAAE,MAAM,OAAO,CAAA;AAGjD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,YAAY,CAAA;AAErD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;uBAEmB;IACnB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAA;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAAA;CAC/D;AA+DD,wBAAgB,gBAAgB,IAAI,aAAa,CAYhD"}

package/dist/tools/shell-provider.js

@@ -14,6 +14,7 @@ function createPosixProvider(executable, type) {
                 timeout: opts.timeout,
                 cwd: opts.cwd,
                 reject: false,
+                cancelSignal: opts.signal,
                 env: { ...(opts.env ?? process.env), PYTHONIOENCODING: 'utf-8' },
             });
         },
@@ -53,6 +54,7 @@ function createPowerShellProvider(executable) {
                 timeout: opts.timeout,
                 cwd: opts.cwd,
                 reject: false,
+                cancelSignal: opts.signal,
                 env: { ...(opts.env ?? process.env), PYTHONIOENCODING: 'utf-8' },
             });
         },

package/dist/tools/shell-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"shell-provider.js","sourceRoot":"","sources":["../../src/tools/shell-provider.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,0CAA0C;AAC1C,OAAO,EAAE,KAAK,EAAsB,MAAM,OAAO,CAAA;AACjD,OAAO,EAAE,MAAM,SAAS,CAAA;AAexB,SAAS,mBAAmB,CAAC,UAAkB,EAAE,IAAoB;IACnE,OAAO;QACL,IAAI;QACJ,KAAK,CAAC,OAAO,EAAE,IAAI;YACjB,OAAO,KAAK,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE;gBACxC,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,MAAM,EAAE,KAAK;gBACb,GAAG,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,gBAAgB,EAAE,OAAO,EAAE;aACjE,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC;AAED,+EAA+E;AAC/E,4EAA4E;AAC5E,8EAA8E;AAC9E,yBAAyB;AACzB,SAAS,uBAAuB,CAAC,SAAiB;IAChD,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;AAC7D,CAAC;AAED,SAAS,wBAAwB,CAAC,UAAkB;IAClD,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,KAAK,CAAC,OAAO,EAAE,IAAI;YACjB,6DAA6D;YAC7D,wEAAwE;YACxE,mEAAmE;YACnE,gDAAgD;YAChD,qEAAqE;YACrE,qEAAqE;YACrE,4BAA4B;YAC5B,oEAAoE;YACpE,qEAAqE;YACrE,uEAAuE;YACvE,qEAAqE;YACrE,iEAAiE;YACjE,MAAM,OAAO,GAAG;gBACd,0DAA0D;gBAC1D,0CAA0C;gBAC1C,OAAO;gBACP,qFAAqF;gBACrF,YAAY;aACb,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACZ,OAAO,KAAK,CACV,UAAU,EACV,CAAC,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,uBAAuB,CAAC,OAAO,CAAC,CAAC,EACtF;gBACE,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,MAAM,EAAE,KAAK;gBACb,GAAG,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,gBAAgB,EAAE,OAAO,EAAE;aACjE,CACF,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,IAAI,EAAE,CAAC,QAAQ,EAAE,KAAK,OAAO,EAAE,CAAC;QAC9B,wEAAwE;QACxE,6DAA6D;QAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAA;QAC/B,IAAI,KAAK,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1C,OAAO,mBAAmB,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;QAC3E,CAAC;QACD,OAAO,wBAAwB,CAAC,gBAAgB,CAAC,CAAA;IACnD,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,WAAW,CAAA;IAClD,OAAO,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AACnF,CAAC"}
+{"version":3,"file":"shell-provider.js","sourceRoot":"","sources":["../../src/tools/shell-provider.ts"],"names":[],"mappings":"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"}

package/dist/tools/task.d.ts

@@ -0,0 +1,14 @@
+import type { SubAgentRegistry } from '../agent/sub-agents/registry.js';
+/** Build the task tool description dynamically from the registry.
+ *  Called once per session when constructing the system prompt cache.
+ *  The listing of available agents is embedded in the description so
+ *  the model knows what subagent_type values are valid. */
+export declare function buildTaskToolDescription(registry: SubAgentRegistry): string;
+/** Create the task tool definition. Must be called with the registry
+ *  so the description includes the available agent list. */
+export declare function createTaskTool(registry: SubAgentRegistry): import("ai").Tool<{
+    description: string;
+    prompt: string;
+    subagent_type: string;
+}, never>;
+//# sourceMappingURL=task.d.ts.map

package/dist/tools/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/tools/task.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAEvE;;;2DAG2D;AAC3D,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAoE3E;AAED;4DAC4D;AAC5D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB;;;;UAcxD"}

package/dist/tools/task.js

@@ -0,0 +1,95 @@
+// @x-code-cli/core — task tool (sub-agent dispatch)
+//
+// The tool definition has no `execute` — dispatch is handled manually
+// in tool-execution.ts's handleToolCall, which calls runSubAgent.
+// This is intentional: the task tool needs access to LoopState,
+// AgentOptions, and callbacks that aren't available in the tool's
+// execute context.
+import { tool } from 'ai';
+import { z } from 'zod';
+/** Build the task tool description dynamically from the registry.
+ *  Called once per session when constructing the system prompt cache.
+ *  The listing of available agents is embedded in the description so
+ *  the model knows what subagent_type values are valid. */
+export function buildTaskToolDescription(registry) {
+    const agents = registry.list();
+    const agentList = agents
+        .map((a) => `  - ${a.name}: ${a.description}`)
+        .join('\n');
+    return `Launch a sub-agent to handle a task in an isolated context. The sub-agent runs with its own message history and returns only its final conclusion — its intermediate tool calls never enter your context window, keeping the main conversation lean.
+
+Available sub-agents:
+${agentList}
+
+## When to use
+
+Use the task tool when intermediate tool output isn't worth keeping in your context:
+- **Research / exploration**: open-ended questions about the codebase ("where is X defined", "find all callers of Y", "what test patterns does this project use")
+- **Code review**: reviewing pending changes or specific files for bugs, security issues, style violations
+- **Implementation planning**: designing an approach that requires reading many files before writing any
+- **Multi-step investigation**: tasks that need 3+ tool calls whose raw output you don't need to see — only the conclusion matters
+
+## When NOT to use
+
+Do NOT delegate when a direct tool call is faster or when you need the result in-context:
+- If you want to read a specific file, use readFile directly
+- If you are searching for a specific symbol like "class Foo", use grep directly
+- If you are searching code within 1-3 known files, use readFile directly
+- Simple single-step tasks (typo fix, add a comment, run one command)
+- Tasks where your immediate next step depends on the raw output — do them locally to keep the critical path moving
+- The user asked a simple question you can answer directly
+
+## Writing the prompt
+
+Brief the sub-agent like a smart colleague who just walked into the room — it has zero prior context: hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
+- Explain what you're trying to accomplish and why.
+- Describe what you've already learned or ruled out.
+- Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.
+- Include concrete details: file paths, function names, line numbers, error messages.
+- If you need a short response, say so ("report in under 200 words").
+- For lookups: hand over the exact command. For investigations: hand over the question — prescribed steps become dead weight when the premise is wrong.
+
+Terse command-style prompts produce shallow, generic work.
+
+**Never delegate understanding.** Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.
+
+## Concurrency safety
+
+NEVER launch multiple sub-agents in one turn if they could modify the same files or resources. Only run multiple sub-agents in parallel when their tasks are genuinely independent (e.g., two read-only research questions about different parts of the codebase).
+
+## Example
+
+<example>
+user: "Can you check if there are any security issues in the auth module?"
+assistant: I'll have the code reviewer check the auth module.
+task({
+  description: "Review auth module security",
+  subagent_type: "code-reviewer",
+  prompt: "Review the authentication module for security issues. The main auth code lives in src/auth/. Focus on: JWT token handling in src/auth/jwt.ts, session management in src/auth/session.ts, and the login endpoint in src/routes/login.ts. Check for: token expiration handling, secret storage, injection vulnerabilities, and missing input validation. Report a numbered punch list with severity and file:line references."
+})
+</example>
+
+<example>
+user: "Fix the typo in README"
+<commentary>Do NOT use task — this is a single-step edit. Just use the edit tool directly.</commentary>
+</example>
+
+<example>
+user: "What does the glob tool do?"
+<commentary>Do NOT use task — this is a direct Q&A question you can answer from your own knowledge.</commentary>
+</example>`;
+}
+/** Create the task tool definition. Must be called with the registry
+ *  so the description includes the available agent list. */
+export function createTaskTool(registry) {
+    return tool({
+        description: buildTaskToolDescription(registry),
+        inputSchema: z.object({
+            description: z.string().describe('A short (3-5 words) description of the task'),
+            subagent_type: z.string().describe(`Which sub-agent to use. Available: ${registry.names().join(', ')}`),
+            prompt: z.string().describe('The complete task instruction sent to the sub-agent. Be specific — the sub-agent has no prior context.'),
+        }),
+        // No execute — handled manually in tool-execution.ts
+    });
+}
+//# sourceMappingURL=task.js.map

package/dist/tools/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/tools/task.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,sEAAsE;AACtE,kEAAkE;AAClE,gEAAgE;AAChE,kEAAkE;AAClE,mBAAmB;AACnB,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AACzB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB;;;2DAG2D;AAC3D,MAAM,UAAU,wBAAwB,CAAC,QAA0B;IACjE,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAA;IAC9B,MAAM,SAAS,GAAG,MAAM;SACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;SAC7C,IAAI,CAAC,IAAI,CAAC,CAAA;IAEb,OAAO;;;EAGP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA0DA,CAAA;AACX,CAAC;AAED;4DAC4D;AAC5D,MAAM,UAAU,cAAc,CAAC,QAA0B;IACvD,OAAO,IAAI,CAAC;QACV,WAAW,EAAE,wBAAwB,CAAC,QAAQ,CAAC;QAC/C,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;YAC/E,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAChC,sCAAsC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpE;YACD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CACzB,wGAAwG,CACzG;SACF,CAAC;QACF,qDAAqD;KACtD,CAAC,CAAA;AACJ,CAAC"}

package/dist/tools/todo-write.d.ts

@@ -0,0 +1,21 @@
+/** The model maintains a working checklist via this tool. Each call
+ *  REPLACES the entire list (no merge / no delta) — the model is told
+ *  to pass the full updated array every time, including unchanged items.
+ *  When all items are completed, the agent loop auto-clears the list to
+ *  free the live UI panel.
+ *
+ *  Storage: in-memory on `LoopState.todos`, mirrored to React state via
+ *  `callbacks.onTodosUpdate`. Never persisted to disk (matches Claude
+ *  Code) — checklists are session-scoped working memory, not records.
+ *
+ *  No `execute` field — the side-effect (mutating LoopState.todos and
+ *  notifying the UI) is handled manually in `processToolCalls`. Same
+ *  pattern as askUser / enterPlanMode. */
+export declare const todoWrite: import("ai").Tool<{
+    todos: {
+        content?: string | undefined;
+        status?: "pending" | "in_progress" | "completed" | undefined;
+        activeForm?: string | undefined;
+    }[];
+}, never>;
+//# sourceMappingURL=todo-write.d.ts.map

package/dist/tools/todo-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-write.d.ts","sourceRoot":"","sources":["../../src/tools/todo-write.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;0CAY0C;AAC1C,eAAO,MAAM,SAAS;;;;;;SAqGpB,CAAA"}

package/dist/tools/todo-write.js

@@ -0,0 +1,117 @@
+// @x-code-cli/core — todoWrite tool (model-managed checklist, no execute — handled in agent loop)
+import { tool } from 'ai';
+import { z } from 'zod';
+/** The model maintains a working checklist via this tool. Each call
+ *  REPLACES the entire list (no merge / no delta) — the model is told
+ *  to pass the full updated array every time, including unchanged items.
+ *  When all items are completed, the agent loop auto-clears the list to
+ *  free the live UI panel.
+ *
+ *  Storage: in-memory on `LoopState.todos`, mirrored to React state via
+ *  `callbacks.onTodosUpdate`. Never persisted to disk (matches Claude
+ *  Code) — checklists are session-scoped working memory, not records.
+ *
+ *  No `execute` field — the side-effect (mutating LoopState.todos and
+ *  notifying the UI) is handled manually in `processToolCalls`. Same
+ *  pattern as askUser / enterPlanMode. */
+export const todoWrite = tool({
+    description: `Use this tool to track multi-step tasks. The user sees a live checklist (☐ ◼ ✔) above the spinner — it makes long tasks feel structured and gives them visibility into your plan.
+
+## When to Use
+
+- Multi-step tasks that involve 3+ logical steps
+- Right after exitPlanMode is approved and you have an approved plan with several files / phases — translate the plan into todos before starting work
+- The user gives multiple requests in one message ("do A, then B, then C")
+- When you start a step (mark it \`in_progress\` BEFORE doing the work)
+- When you finish a step (mark it \`completed\` IMMEDIATELY, not at the end)
+
+## When NOT to Use
+
+- Single-file edits, typos, trivial fixes — todos add ceremony with no benefit
+- Pure Q&A or research questions
+- Tasks doable in 1-2 obvious steps
+- Conversational replies that don't involve concrete work
+
+## Hard Rules
+
+1. **Status values**: \`pending\` | \`in_progress\` | \`completed\` (exactly these three).
+2. **Exactly ONE task in_progress at any time** — not zero, not two. The user reads the in_progress one as "what the agent is doing right now".
+3. **Mark complete IMMEDIATELY after finishing** — don't batch completions at the end of the run. The user wants live feedback.
+4. **Only mark complete when truly done** — if tests are failing, the implementation is partial, you hit an error, or you're going to follow up later: leave it as \`in_progress\` and add a NEW pending todo describing the unresolved part.
+5. **Provide both \`content\` and \`activeForm\`**:
+   - \`content\` is imperative: "Run tests", "Update auth handler"
+   - \`activeForm\` is present-continuous: "Running tests", "Updating auth handler"
+   - The activeForm is what shows in the live UI for the in_progress item.
+6. **Pass the FULL list every call** — todoWrite REPLACES the list, not merges. Include unchanged items.
+7. When you submit a list where every item is \`completed\`, the system auto-clears the checklist for you. No need to clear it manually.
+
+## Example
+
+User: "Refactor the auth system to use JWT and update the login flow"
+
+After exploration / planning, on the first implementation turn:
+\`\`\`
+todoWrite({
+  todos: [
+    { content: "Read existing auth implementation",  activeForm: "Reading auth code",        status: "in_progress" },
+    { content: "Add JWT signing/verification utility", activeForm: "Adding JWT utility",     status: "pending" },
+    { content: "Update login handler",               activeForm: "Updating login",          status: "pending" },
+    { content: "Update protected routes middleware", activeForm: "Updating middleware",     status: "pending" },
+    { content: "Add tests for new auth flow",        activeForm: "Writing auth tests",      status: "pending" }
+  ]
+})
+\`\`\`
+
+After reading the code:
+\`\`\`
+todoWrite({
+  todos: [
+    { content: "Read existing auth implementation",  activeForm: "Reading auth code",        status: "completed" },
+    { content: "Add JWT signing/verification utility", activeForm: "Adding JWT utility",     status: "in_progress" },
+    ...rest stay pending
+  ]
+})
+\`\`\`
+
+After finishing all five (auto-cleared next call):
+\`\`\`
+todoWrite({ todos: [/* all five with status: "completed" */] })
+\`\`\`
+
+## Bad usage
+
+User: "fix this typo in README"
+You: <do not call todoWrite — single edit, no value in a checklist>
+
+User: "what does X do?"
+You: <do not call todoWrite — pure Q&A, no work to track>`,
+    // SCHEMA LENIENCY (deliberate): all three per-todo fields are
+    // marked optional even though the tool description tells the model
+    // they are required. Reason: weaker provider models (DeepSeek-flash,
+    // GLM, Qwen, etc.) routinely drop one field per item — most often
+    // `status` on the last "current" entry, sometimes `content` when
+    // they think `activeForm` is enough. With strict requireds, Zod
+    // rejects the whole call → SDK emits tool-error → assistant
+    // tool_call with no result → next API turn fails with "tool must
+    // be a response to tool_calls". Validating loosely and synthesising
+    // sane defaults in the dispatch handler is dramatically more robust
+    // than playing whack-a-mole with model output. Strong models
+    // (Sonnet, Opus) still get the same rich description telling them
+    // to provide all three fields.
+    inputSchema: z.object({
+        todos: z
+            .array(z.object({
+            content: z.string().optional().describe('Imperative phrasing of the task ("Run tests").'),
+            activeForm: z
+                .string()
+                .optional()
+                .describe('Present-continuous phrasing ("Running tests"); shown in the live UI when this item is in_progress.'),
+            status: z
+                .enum(['pending', 'in_progress', 'completed'])
+                .optional()
+                .describe('Lifecycle state. Exactly one item should be in_progress at any time. Defaults to "pending" if omitted.'),
+        }))
+            .describe('The complete updated todo list. Every call REPLACES the existing list — include all items even if unchanged.'),
+    }),
+});
+//# sourceMappingURL=todo-write.js.map

package/dist/tools/todo-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-write.js","sourceRoot":"","sources":["../../src/tools/todo-write.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAEzB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;;0CAY0C;AAC1C,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0DAqE2C;IACxD,8DAA8D;IAC9D,mEAAmE;IACnE,qEAAqE;IACrE,kEAAkE;IAClE,iEAAiE;IACjE,gEAAgE;IAChE,4DAA4D;IAC5D,iEAAiE;IACjE,oEAAoE;IACpE,oEAAoE;IACpE,6DAA6D;IAC7D,kEAAkE;IAClE,+BAA+B;IAC/B,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,KAAK,EAAE,CAAC;aACL,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;YACzF,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,oGAAoG,CAAC;YACjH,MAAM,EAAE,CAAC;iBACN,IAAI,CAAC,CAAC,SAAS,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC;iBAC7C,QAAQ,EAAE;iBACV,QAAQ,CAAC,wGAAwG,CAAC;SACtH,CAAC,CACH;aACA,QAAQ,CAAC,8GAA8G,CAAC;KAC5H,CAAC;CACH,CAAC,CAAA"}