actoviq-agent-sdk 0.2.0 → 0.3.1

package/dist/src/tools/bash/prompt.js

@@ -0,0 +1,63 @@
+export const BASH_TOOL_NAME = 'Bash';
+export const BASH_DESCRIPTION = `Executes a given bash command and returns its output.
+
+The working directory persists between commands, but shell state does not. The shell environment is initialized from the user's profile (bash or zsh).
+
+IMPORTANT: Avoid using this tool to run \`find\`, \`grep\`, \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
+
+- File search: Use Glob (NOT find or ls)
+- Content search: Use Grep (NOT grep or rg)
+- Read files: Use Read (NOT cat/head/tail)
+- Edit files: Use Edit (NOT sed/awk)
+- Write files: Use Write (NOT echo >/cat <<EOF)
+- Communication: Output text directly (NOT echo/printf)
+
+While the Bash tool can do similar things, it's better to use the built-in tools as they provide a better user experience and make it easier to review tool calls and give permission.
+
+# Instructions
+
+- If your command will create new directories or files, first use this tool to run \`ls\` to verify the parent directory exists and is the correct location.
+- Always quote file paths that contain spaces with double quotes in your command (e.g., cd "path with spaces/file.txt")
+- Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of \`cd\`. You may use \`cd\` if the User explicitly requests it.
+- You may specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). By default, your command will timeout after 120000ms (2 minutes).
+- You can use the \`run_in_background\` parameter to run the command in the background. Only use this if you don't need the result immediately and are OK being notified when the command completes later. You do not need to check the output right away - you'll be notified when it finishes. You do not need to use '&' at the end of the command when using this parameter.
+- When issuing multiple commands:
+  - If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message. Example: if you need to run "git status" and "git diff", send a single message with two Bash tool calls in parallel.
+  - If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together.
+  - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail.
+  - DO NOT use newlines to separate commands (newlines are ok in quoted strings).
+- For git commands:
+  - Prefer to create a new commit rather than amending an existing commit.
+  - Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.
+  - Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.
+- Avoid unnecessary \`sleep\` commands:
+  - Do not sleep between commands that can run immediately — just run them.
+  - If your command is long running and you would like to be notified when it finishes — use \`run_in_background\`. No sleep needed.
+  - Do not retry failing commands in a sleep loop — diagnose the root cause.
+  - If waiting for a background task you started with \`run_in_background\`, you will be notified when it completes — do not poll.
+  - If you must poll an external process, use a check command rather than sleeping first.
+  - If you must sleep, keep the duration short to avoid blocking the user.
+
+# Committing changes with git
+
+Only create commits when requested by the user. If unclear, ask first. When the user asks you to create a new git commit, follow these steps carefully:
+
+Git Safety Protocol:
+- NEVER update the git config
+- NEVER run destructive git commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) unless the user explicitly requests these actions.
+- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it
+- NEVER run force push to main/master, warn the user if they request it
+- CRITICAL: Always create NEW commits rather than amending, unless the user explicitly requests a git amend.
+- When staging files, prefer adding specific files by name rather than using "git add -A" or "git add ."
+- NEVER commit changes unless the user explicitly asks you to.
+
+1. Run the following bash commands in parallel:
+  - git status to see all untracked files (never use -uall flag)
+  - git diff to see both staged and unstaged changes
+  - git log to see recent commit messages
+2. Draft a commit message (1-2 sentences) focusing on "why" rather than "what"
+3. Create the commit and run git status to verify.
+4. If the commit fails due to pre-commit hook: fix the issue and create a NEW commit
+
+Important: NEVER use git commands with the -i flag since they require interactive input. If there are no changes to commit, do not create an empty commit. ALWAYS pass the commit message via a HEREDOC.`;
+//# sourceMappingURL=prompt.js.map

package/dist/src/tools/bash/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../../../src/tools/bash/prompt.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AAErC,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yMA4DyK,CAAC"}

package/dist/src/tools/prompts/fileEditPrompt.d.ts

@@ -0,0 +1,3 @@
+export declare const FILE_EDIT_TOOL_NAME = "Edit";
+export declare function fileEditPrompt(_options?: any): string;
+//# sourceMappingURL=fileEditPrompt.d.ts.map

package/dist/src/tools/prompts/fileEditPrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileEditPrompt.d.ts","sourceRoot":"","sources":["../../../../src/tools/prompts/fileEditPrompt.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAE1C,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,GAAG,GAAG,MAAM,CAUrD"}

package/dist/src/tools/prompts/fileEditPrompt.js

@@ -0,0 +1,14 @@
+import { FILE_READ_TOOL_NAME } from './fileReadPrompt.js';
+export const FILE_EDIT_TOOL_NAME = 'Edit';
+export function fileEditPrompt(_options) {
+    return `Performs exact string replacements in files.
+
+Usage:
+- You must use your \`${FILE_READ_TOOL_NAME}\` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
+- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: line number + tab. Everything after that is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if \`old_string\` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use \`replace_all\` to change every instance of \`old_string\`.
+- Use \`replace_all\` for replacing and renaming strings across the file.`;
+}
+//# sourceMappingURL=fileEditPrompt.js.map

package/dist/src/tools/prompts/fileEditPrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileEditPrompt.js","sourceRoot":"","sources":["../../../../src/tools/prompts/fileEditPrompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAE1C,MAAM,UAAU,cAAc,CAAC,QAAc;IAC3C,OAAO;;;wBAGe,mBAAmB;;;;;0EAK+B,CAAC;AAC3E,CAAC"}

package/dist/src/tools/prompts/fileReadPrompt.d.ts

@@ -0,0 +1,3 @@
+export declare const FILE_READ_TOOL_NAME = "Read";
+export declare function fileReadPrompt(_options?: any): string;
+//# sourceMappingURL=fileReadPrompt.d.ts.map

package/dist/src/tools/prompts/fileReadPrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileReadPrompt.d.ts","sourceRoot":"","sources":["../../../../src/tools/prompts/fileReadPrompt.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAE1C,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,GAAG,GAAG,MAAM,CAerD"}

package/dist/src/tools/prompts/fileReadPrompt.js

@@ -0,0 +1,18 @@
+export const FILE_READ_TOOL_NAME = 'Read';
+export function fileReadPrompt(_options) {
+    return `Reads a file from the local filesystem. You can access any file directly by using this tool.
+Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- By default, it reads up to 2000 lines starting from the beginning of the file
+- When you already know which part of the file you need, only read that part. This can be important for larger files.
+- Results are returned using cat -n format, with line numbers starting at 1
+- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.
+- This tool can read PDF files (.pdf). For large PDFs (more than 10 pages), you MUST provide the pages parameter to read specific page ranges (e.g., pages: "1-5"). Maximum 20 pages per request.
+- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs.
+- This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.
+- If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path.
+- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.`;
+}
+//# sourceMappingURL=fileReadPrompt.js.map

package/dist/src/tools/prompts/fileReadPrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileReadPrompt.js","sourceRoot":"","sources":["../../../../src/tools/prompts/fileReadPrompt.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAE1C,MAAM,UAAU,cAAc,CAAC,QAAc;IAC3C,OAAO;;;;;;;;;;;;;8HAaqH,CAAC;AAC/H,CAAC"}

package/dist/src/tools/prompts/fileSearchPrompt.d.ts

@@ -0,0 +1,2 @@
+export declare function fileSearchPrompt(_options?: any): string;
+//# sourceMappingURL=fileSearchPrompt.d.ts.map

package/dist/src/tools/prompts/fileSearchPrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileSearchPrompt.d.ts","sourceRoot":"","sources":["../../../../src/tools/prompts/fileSearchPrompt.ts"],"names":[],"mappings":"AAEA,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,GAAG,GAAG,MAAM,CAmBvD"}

package/dist/src/tools/prompts/fileSearchPrompt.js

@@ -0,0 +1,21 @@
+export function fileSearchPrompt(_options) {
+    return `## File Search Tools (Glob & Grep)
+
+### Glob
+- Fast file pattern matching tool for finding files by name patterns.
+- Supports glob patterns like \`**/*.js\` or \`src/**/*.ts\`.
+- Returns matching file paths sorted by modification time.
+- Use this tool when you need to find files by name patterns.
+
+### Grep
+- A powerful search tool built on regular expressions for searching file contents.
+- Usage:
+  - ALWAYS use Grep for search tasks. NEVER invoke \`grep\` or \`rg\` as a Bash command.
+  - Supports full regex syntax with \`pattern\` parameter.
+  - Filter files with \`glob\` parameter (e.g., \`"*.js"\`, \`"**/*.tsx"\`).
+  - Output modes: \`"content"\` shows matching lines, \`"files_with_matches"\` shows only file paths (default), \`"count"\` shows match counts.
+  - Use \`head_limit\` to limit output. Pass 0 for unlimited.
+  - Supports context lines (\`-A\`, \`-B\`, \`-C\`) and multiline mode.
+- If you are searching for a keyword or file and are not confident that you will find the right match in the first few tries, keep searching with different patterns.`;
+}
+//# sourceMappingURL=fileSearchPrompt.js.map

package/dist/src/tools/prompts/fileSearchPrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileSearchPrompt.js","sourceRoot":"","sources":["../../../../src/tools/prompts/fileSearchPrompt.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,gBAAgB,CAAC,QAAc;IAC7C,OAAO;;;;;;;;;;;;;;;;;sKAiB6J,CAAC;AACvK,CAAC"}

package/dist/src/tools/prompts/fileWritePrompt.d.ts

@@ -0,0 +1,3 @@
+export declare const FILE_WRITE_TOOL_NAME = "Write";
+export declare function fileWritePrompt(_options?: any): string;
+//# sourceMappingURL=fileWritePrompt.d.ts.map

package/dist/src/tools/prompts/fileWritePrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileWritePrompt.d.ts","sourceRoot":"","sources":["../../../../src/tools/prompts/fileWritePrompt.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,GAAG,GAAG,MAAM,CAStD"}

package/dist/src/tools/prompts/fileWritePrompt.js

@@ -0,0 +1,13 @@
+import { FILE_READ_TOOL_NAME } from './fileReadPrompt.js';
+export const FILE_WRITE_TOOL_NAME = 'Write';
+export function fileWritePrompt(_options) {
+    return `Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the \`${FILE_READ_TOOL_NAME}\` tool first to read the file's contents. This tool will fail if you did not read the file first.
+- Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
+- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.`;
+}
+//# sourceMappingURL=fileWritePrompt.js.map

package/dist/src/tools/prompts/fileWritePrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileWritePrompt.js","sourceRoot":"","sources":["../../../../src/tools/prompts/fileWritePrompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAE5C,MAAM,UAAU,eAAe,CAAC,QAAc;IAC5C,OAAO;;;;oDAI2C,mBAAmB;;;kGAG2B,CAAC;AACnG,CAAC"}

package/dist/src/tools/prompts/webFetchPrompt.d.ts

@@ -0,0 +1,3 @@
+import type { ToolPromptOptions } from '../../types.js';
+export declare function webFetchPrompt(_options: ToolPromptOptions): string;
+//# sourceMappingURL=webFetchPrompt.d.ts.map

package/dist/src/tools/prompts/webFetchPrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webFetchPrompt.d.ts","sourceRoot":"","sources":["../../../../src/tools/prompts/webFetchPrompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAWlE"}

package/dist/src/tools/prompts/webFetchPrompt.js

@@ -0,0 +1,13 @@
+export function webFetchPrompt(_options) {
+    return `## WebFetch Tool
+- Fetches content from a specified URL and processes it.
+- Usage:
+  - The URL must be a fully-formed valid URL.
+  - HTTP URLs will be automatically upgraded to HTTPS.
+  - The \`prompt\` parameter describes what information to extract from the page.
+  - This tool is read-only and does not modify any files.
+  - Results may be summarized if the content is very large (max ~50KB).
+  - IMPORTANT: You MUST never generate or guess URLs. Only use URLs provided by the user or found in previous tool results.
+- For GitHub URLs, prefer using the gh CLI tool instead when available.`;
+}
+//# sourceMappingURL=webFetchPrompt.js.map

package/dist/src/tools/prompts/webFetchPrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webFetchPrompt.js","sourceRoot":"","sources":["../../../../src/tools/prompts/webFetchPrompt.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,cAAc,CAAC,QAA2B;IACxD,OAAO;;;;;;;;;wEAS+D,CAAC;AACzE,CAAC"}

package/dist/src/tools/prompts/webSearchPrompt.d.ts

@@ -0,0 +1,3 @@
+import type { ToolPromptOptions } from '../../types.js';
+export declare function webSearchPrompt(_options: ToolPromptOptions): string;
+//# sourceMappingURL=webSearchPrompt.d.ts.map

package/dist/src/tools/prompts/webSearchPrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webSearchPrompt.d.ts","sourceRoot":"","sources":["../../../../src/tools/prompts/webSearchPrompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAenE"}

package/dist/src/tools/prompts/webSearchPrompt.js

@@ -0,0 +1,17 @@
+export function webSearchPrompt(_options) {
+    return `## WebSearch Tool
+- Searches the web and returns results with titles, URLs, and snippets.
+- Uses DuckDuckGo for zero-configuration searching.
+- Usage:
+  - The \`query\` parameter must be at least 2 characters.
+  - Use \`limit\` to control the number of results (default: 5, max recommended: 10).
+  - Domain filtering is supported to include or block specific websites.
+
+CRITICAL REQUIREMENT - You MUST follow this:
+  - After answering the user's question, you MUST include a "Sources:" section at the end of your response
+  - In the Sources section, list all relevant URLs from the search results as markdown hyperlinks: [Title](URL)
+  - This is MANDATORY - never skip including sources in your response
+
+IMPORTANT: If you need up-to-date information or information beyond your knowledge cutoff, use this tool.`;
+}
+//# sourceMappingURL=webSearchPrompt.js.map

package/dist/src/tools/prompts/webSearchPrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webSearchPrompt.js","sourceRoot":"","sources":["../../../../src/tools/prompts/webSearchPrompt.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,eAAe,CAAC,QAA2B;IACzD,OAAO;;;;;;;;;;;;;0GAaiG,CAAC;AAC3G,CAAC"}

package/dist/src/tools/todo/TodoWriteTool.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import type { AgentToolDefinition } from '../../types.js';
+export declare const TODO_WRITE_TOOL_NAME = "TodoWrite";
+declare const TodoItemSchema: z.ZodObject<{
+    content: z.ZodString;
+    status: z.ZodEnum<{
+        completed: "completed";
+        pending: "pending";
+        in_progress: "in_progress";
+    }>;
+    activeForm: z.ZodString;
+}, z.core.$strip>;
+export declare const TODO_PROMPT = "Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.\n\n## When to Use This Tool\nUse proactively in these scenarios:\n\n1. Complex multi-step tasks - 3 or more distinct steps\n2. Non-trivial tasks requiring careful planning\n3. User explicitly requests todo list\n4. User provides multiple tasks (numbered or comma-separated)\n5. After receiving new instructions - capture requirements as todos\n6. When starting a task - mark it in_progress BEFORE beginning (limit ONE at a time)\n7. After completing a task - mark completed, add follow-up tasks discovered\n\n## When NOT to Use\nSkip when: single straightforward task, trivial task, purely conversational/informational request.\n\n## Task States and Management\n\n1. Task States: pending, in_progress, completed\n   - content: imperative form describing what to do (e.g., \"Run tests\")\n   - activeForm: present continuous form shown during execution (e.g., \"Running tests\")\n\n2. Task Management:\n   - Update status in real-time, mark complete IMMEDIATELY after finishing\n   - Exactly ONE task in_progress at any time\n   - Complete current tasks before starting new ones\n   - Remove irrelevant tasks from the list\n\n3. Task Completion Requirements:\n   - ONLY mark completed when FULLY accomplished\n   - If you encounter errors or cannot finish, keep in_progress\n   - When blocked, create a new task describing the issue\n\nWhen in doubt, use this tool. Proactive task management demonstrates attentiveness.";
+export declare const TODO_DESCRIPTION = "Update the todo list for the current session. To be used proactively to track progress and pending tasks. At least one task should be in_progress at all times. Always provide both content (imperative) and activeForm (present continuous) for each task.";
+type TodoItem = z.infer<typeof TodoItemSchema>;
+export declare function getActoviqTodoSnapshot(scopeKey: string): TodoItem[];
+export declare function formatActoviqTodoListLines(todos: TodoItem[]): string;
+export declare function createTodoWriteTool(): AgentToolDefinition;
+export {};
+//# sourceMappingURL=TodoWriteTool.d.ts.map

package/dist/src/tools/todo/TodoWriteTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TodoWriteTool.d.ts","sourceRoot":"","sources":["../../../../src/tools/todo/TodoWriteTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAIhD,QAAA,MAAM,cAAc;;;;;;;;iBAIlB,CAAC;AAIH,eAAO,MAAM,WAAW,2kDAiC4D,CAAC;AAErF,eAAO,MAAM,gBAAgB,gQACkO,CAAC;AAEhQ,KAAK,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAqB/C,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,CAEnE;AAQD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CAEpE;AAeD,wBAAgB,mBAAmB,IAAI,mBAAmB,CAqBzD"}

package/dist/src/tools/todo/TodoWriteTool.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { tool } from '../../runtime/tools.js';
+export const TODO_WRITE_TOOL_NAME = 'TodoWrite';
+const TodoStatusSchema = z.enum(['pending', 'in_progress', 'completed']);
+const TodoItemSchema = z.object({
+    content: z.string().min(1, 'Content cannot be empty'),
+    status: TodoStatusSchema,
+    activeForm: z.string().min(1, 'Active form cannot be empty'),
+});
+const TodoListSchema = z.array(TodoItemSchema);
+export const TODO_PROMPT = `Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+
+## When to Use This Tool
+Use proactively in these scenarios:
+
+1. Complex multi-step tasks - 3 or more distinct steps
+2. Non-trivial tasks requiring careful planning
+3. User explicitly requests todo list
+4. User provides multiple tasks (numbered or comma-separated)
+5. After receiving new instructions - capture requirements as todos
+6. When starting a task - mark it in_progress BEFORE beginning (limit ONE at a time)
+7. After completing a task - mark completed, add follow-up tasks discovered
+
+## When NOT to Use
+Skip when: single straightforward task, trivial task, purely conversational/informational request.
+
+## Task States and Management
+
+1. Task States: pending, in_progress, completed
+   - content: imperative form describing what to do (e.g., "Run tests")
+   - activeForm: present continuous form shown during execution (e.g., "Running tests")
+
+2. Task Management:
+   - Update status in real-time, mark complete IMMEDIATELY after finishing
+   - Exactly ONE task in_progress at any time
+   - Complete current tasks before starting new ones
+   - Remove irrelevant tasks from the list
+
+3. Task Completion Requirements:
+   - ONLY mark completed when FULLY accomplished
+   - If you encounter errors or cannot finish, keep in_progress
+   - When blocked, create a new task describing the issue
+
+When in doubt, use this tool. Proactive task management demonstrates attentiveness.`;
+export const TODO_DESCRIPTION = 'Update the todo list for the current session. To be used proactively to track progress and pending tasks. At least one task should be in_progress at all times. Always provide both content (imperative) and activeForm (present continuous) for each task.';
+// Todo state is scoped per session (falling back to run) so long sessions can
+// re-read prior state and the result snapshot stays accurate across turns.
+const MAX_TRACKED_TODO_SCOPES = 256;
+const todoStateByScope = new Map();
+function rememberTodos(scopeKey, todos) {
+    const previous = todoStateByScope.get(scopeKey) ?? [];
+    // Refresh insertion order so the eviction below drops the stalest scope.
+    todoStateByScope.delete(scopeKey);
+    todoStateByScope.set(scopeKey, todos);
+    if (todoStateByScope.size > MAX_TRACKED_TODO_SCOPES) {
+        const oldest = todoStateByScope.keys().next().value;
+        if (oldest !== undefined) {
+            todoStateByScope.delete(oldest);
+        }
+    }
+    return previous;
+}
+export function getActoviqTodoSnapshot(scopeKey) {
+    return todoStateByScope.get(scopeKey) ?? [];
+}
+function formatTodoLine(todo) {
+    const marker = todo.status === 'completed' ? '[x]' : todo.status === 'in_progress' ? '[~]' : '[ ]';
+    const suffix = todo.status === 'in_progress' ? ` (in progress: ${todo.activeForm})` : '';
+    return `${marker} ${todo.content}${suffix}`;
+}
+export function formatActoviqTodoListLines(todos) {
+    return todos.map(formatTodoLine).join('\n');
+}
+function buildTodoResultText(todos) {
+    const lines = formatActoviqTodoListLines(todos);
+    return [
+        'Todos have been modified successfully. Ensure that you continue to use the todo list to track your progress. Please proceed with the current tasks if applicable.',
+        '',
+        '<system-reminder>',
+        'Current todo list state:',
+        lines || '(empty)',
+        'Continue working through pending items; keep exactly one task in_progress.',
+        '</system-reminder>',
+    ].join('\n');
+}
+export function createTodoWriteTool() {
+    return tool({
+        name: TODO_WRITE_TOOL_NAME,
+        description: TODO_DESCRIPTION,
+        inputSchema: z.strictObject({
+            todos: TodoListSchema.describe('The updated todo list'),
+        }),
+        isReadOnly: () => true,
+        prompt: () => TODO_PROMPT,
+        serialize: (output) => buildTodoResultText(output.newTodos),
+    }, async ({ todos }, context) => {
+        const scopeKey = context.sessionId ?? context.runId;
+        const oldTodos = rememberTodos(scopeKey, todos);
+        return {
+            oldTodos,
+            newTodos: todos,
+        };
+    });
+}
+//# sourceMappingURL=TodoWriteTool.js.map

package/dist/src/tools/todo/TodoWriteTool.js.map

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