@bastani/atomic 0.8.29-alpha.2 → 0.8.29-alpha.4

package/dist/core/tools/structured-output.js

@@ -1,55 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { Type } from "typebox";
-import { Value } from "typebox/value";
 import { defineTool } from "../extensions/types.js";
 export const STRUCTURED_OUTPUT_TOOL_NAME = "structured_output";
-const genericStructuredOutputParameters = Type.Object({}, {
-    description: "A top-level JSON object containing the final machine-readable answer.",
-    additionalProperties: Type.Unknown(),
-});
-function schemaTypeIsObjectOnly(type) {
-    if (type === "object")
-        return true;
-    return Array.isArray(type) && type.length === 1 && type[0] === "object";
-}
-function isTopLevelObjectParameterSchema(schema) {
-    if (!schema || typeof schema !== "object" || Array.isArray(schema))
-        return false;
-    const descriptor = schema;
-    if (schemaTypeIsObjectOnly(descriptor.type))
-        return true;
-    if (descriptor.type !== undefined)
-        return false;
-    if (Array.isArray(descriptor.anyOf) || Array.isArray(descriptor.oneOf))
-        return false;
-    if (Array.isArray(descriptor.allOf)) {
-        return descriptor.allOf.length > 0 && descriptor.allOf.every((member) => isTopLevelObjectParameterSchema(member));
-    }
-    return false;
-}
-function assertStructuredOutputParameterSchema(schema, label) {
-    if (isTopLevelObjectParameterSchema(schema))
-        return;
-    throw new Error(`${label} must be a top-level object tool-argument schema. `
-        + "Wrap array or primitive outputs in an object field, for example `{ items: [...] }` or `{ value: ... }`.");
-}
-function formatValidationErrorPath(instancePath) {
-    const normalized = instancePath.replace(/^\//, "").replace(/\//g, ".");
-    return normalized.length > 0 ? normalized : "root";
-}
-function formatValidationErrors(schema, value) {
-    const errors = Value.Errors(schema, value)
-        .slice(0, 8)
-        .map((error) => `${formatValidationErrorPath(error.instancePath)}: ${error.message}`);
-    return errors.join("; ") || "schema validation failed";
-}
-function assertValidParams(schema, params) {
-    if (Value.Check(schema, params)) {
-        return;
-    }
-    throw new Error(`Structured output validation failed: ${formatValidationErrors(schema, params)}`);
-}
 function stringifyParams(params) {
     try {
         return JSON.stringify(params, null, 2);
@@ -58,36 +10,15 @@ function stringifyParams(params) {
         throw new Error(`Structured output must be JSON-serializable: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-export function getStructuredOutputMetadataPath(outputPath) {
-    const directory = path.dirname(outputPath);
-    const basename = path.basename(outputPath);
-    if (basename === "output.json") {
-        return path.join(directory, "output.meta.json");
-    }
-    if (path.extname(basename) === ".json") {
-        return path.join(directory, `${basename.slice(0, -".json".length)}.meta.json`);
-    }
-    return `${outputPath}.meta.json`;
-}
-function createStructuredOutputCaptureMetadata(toolName, toolCallId) {
-    return {
-        toolName,
-        toolCallId,
-        success: true,
-        terminate: true,
-        capturedAt: new Date().toISOString(),
-    };
-}
 async function writePrivateJsonFile(filePath, serializedJson) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
     await fs.writeFile(filePath, serializedJson, { mode: 0o600 });
     // Re-apply the private mode after writing so pre-existing looser files are tightened too.
     await fs.chmod(filePath, 0o600);
 }
-async function writeCapturedOutput(output, serializedParams, metadata) {
+async function writeCapturedOutput(output, serializedParams) {
     try {
         await writePrivateJsonFile(output.outputPath, serializedParams);
-        await writePrivateJsonFile(output.metadataPath ?? getStructuredOutputMetadataPath(output.outputPath), stringifyParams(metadata));
     }
     catch (error) {
         throw new Error(`Failed to write structured output capture: ${error instanceof Error ? error.message : String(error)}`);
@@ -96,40 +27,29 @@ async function writeCapturedOutput(output, serializedParams, metadata) {
 export function createStructuredOutputCapture() {
     return { value: undefined, called: false };
 }
-export function createStructuredOutputTool(options = {}) {
+export function createStructuredOutputTool(options) {
     const name = options.name ?? STRUCTURED_OUTPUT_TOOL_NAME;
-    const schema = (options.schema === undefined ? genericStructuredOutputParameters : options.schema);
-    assertStructuredOutputParameterSchema(schema, `${name} schema`);
-    let outputCalled = false;
-    const hasSingleRunSink = options.capture !== undefined || options.output !== undefined;
     return defineTool({
         name,
         label: "Structured Output",
-        description: "Submit the final machine-readable structured output. This terminates the current agent turn.",
-        promptSnippet: `Submit the final machine-readable answer as a terminating ${name} tool call`,
+        description: "Return the final machine-readable result.",
+        promptSnippet: "Return final machine-readable output",
         promptGuidelines: [
-            `Use ${name} exactly once as your final action when the requested result should be machine-readable or schema-valid.`,
-            "Pass the schema fields directly as tool arguments; do not wrap them in `{ value: ... }` unless the schema explicitly defines a top-level `value` field.",
-            `Do not write prose after calling ${name}; the tool result is the final answer.`,
+            `${name} is the final machine-readable result channel; call ${name} exactly once when done.`,
+            `Do not write a prose final answer after calling ${name}.`,
         ],
-        parameters: schema,
+        parameters: options.schema,
         maxResultSizeChars: Infinity,
         structuredOutput: true,
-        executionMode: "sequential",
-        async execute(toolCallId, params) {
-            assertValidParams(schema, params);
-            if (hasSingleRunSink && (outputCalled || options.capture?.called)) {
-                throw new Error(`${name} was already called for this result contract.`);
-            }
+        async execute(_toolCallId, params) {
             const serializedParams = stringifyParams(params);
             if (options.output) {
-                await writeCapturedOutput(options.output, serializedParams, createStructuredOutputCaptureMetadata(name, toolCallId));
+                await writeCapturedOutput(options.output, serializedParams);
             }
             if (options.capture) {
                 options.capture.value = params;
                 options.capture.called = true;
             }
-            outputCalled = true;
             return {
                 content: [{ type: "text", text: serializedParams }],
                 details: params,

package/dist/core/tools/structured-output.js.map

@@ -1 +1 @@
-{"version":3,"file":"structured-output.js","sourceRoot":"","sources":["../../../src/core/tools/structured-output.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport type { AgentToolResult } from \"@earendil-works/pi-agent-core\";\nimport { Type, type Static, type TSchema } from \"typebox\";\nimport { Value } from \"typebox/value\";\nimport { defineTool, type ToolDefinition } from \"../extensions/types.ts\";\n\nexport const STRUCTURED_OUTPUT_TOOL_NAME = \"structured_output\";\n\nexport type JsonPrimitive = string | number | boolean | null;\nexport type JsonValue = JsonPrimitive | JsonObject | JsonValue[];\nexport type JsonObject = { readonly [key: string]: JsonValue };\n\nexport interface StructuredOutputCapture<TValue> {\n\tvalue: TValue | undefined;\n\tcalled: boolean;\n}\n\nexport interface StructuredOutputFileCapture {\n\toutputPath: string;\n\tmetadataPath?: string;\n}\n\nexport interface StructuredOutputCaptureMetadata {\n\ttoolName: string;\n\ttoolCallId: string;\n\tsuccess: true;\n\tterminate: true;\n\tcapturedAt: string;\n}\n\ntype StructuredOutputParameterSchema = TSchema & {\n\treadonly type?: \"object\" | readonly [\"object\"];\n\treadonly properties?: Record<string, TSchema>;\n\treadonly required?: readonly string[];\n\treadonly additionalProperties?: boolean | TSchema;\n};\n\nexport interface StructuredOutputToolOptions<TSchemaDef extends TSchema = typeof genericStructuredOutputParameters> {\n\t/** Tool parameter schema. Defaults to a generic top-level JSON object. */\n\tschema?: TSchemaDef;\n\t/** In-process result sink for SDK and workflow callers. */\n\tcapture?: StructuredOutputCapture<Static<TSchemaDef>>;\n\t/** Cross-process result sink for subagent child runtimes. */\n\toutput?: StructuredOutputFileCapture;\n\t/** Tool name. Defaults to `structured_output`. */\n\tname?: string;\n}\n\nconst genericStructuredOutputParameters = Type.Object({}, {\n\tdescription: \"A top-level JSON object containing the final machine-readable answer.\",\n\tadditionalProperties: Type.Unknown(),\n});\n\ntype JsonSchemaRootDescriptor = {\n\treadonly type?: string | readonly string[];\n\treadonly anyOf?: readonly TSchema[];\n\treadonly oneOf?: readonly TSchema[];\n\treadonly allOf?: readonly TSchema[];\n};\n\nfunction schemaTypeIsObjectOnly(type: JsonSchemaRootDescriptor[\"type\"]): boolean {\n\tif (type === \"object\") return true;\n\treturn Array.isArray(type) && type.length === 1 && type[0] === \"object\";\n}\n\nfunction isTopLevelObjectParameterSchema(schema: TSchema): boolean {\n\tif (!schema || typeof schema !== \"object\" || Array.isArray(schema)) return false;\n\tconst descriptor = schema as JsonSchemaRootDescriptor;\n\tif (schemaTypeIsObjectOnly(descriptor.type)) return true;\n\tif (descriptor.type !== undefined) return false;\n\tif (Array.isArray(descriptor.anyOf) || Array.isArray(descriptor.oneOf)) return false;\n\tif (Array.isArray(descriptor.allOf)) {\n\t\treturn descriptor.allOf.length > 0 && descriptor.allOf.every((member) => isTopLevelObjectParameterSchema(member));\n\t}\n\treturn false;\n}\n\nfunction assertStructuredOutputParameterSchema(\n\tschema: TSchema,\n\tlabel: string,\n): asserts schema is StructuredOutputParameterSchema {\n\tif (isTopLevelObjectParameterSchema(schema)) return;\n\tthrow new Error(\n\t\t`${label} must be a top-level object tool-argument schema. `\n\t\t+ \"Wrap array or primitive outputs in an object field, for example `{ items: [...] }` or `{ value: ... }`.\",\n\t);\n}\n\nfunction formatValidationErrorPath(instancePath: string): string {\n\tconst normalized = instancePath.replace(/^\\//, \"\").replace(/\\//g, \".\");\n\treturn normalized.length > 0 ? normalized : \"root\";\n}\n\nfunction formatValidationErrors(schema: TSchema, value: unknown): string {\n\tconst errors = Value.Errors(schema, value)\n\t\t.slice(0, 8)\n\t\t.map((error) => `${formatValidationErrorPath(error.instancePath)}: ${error.message}`);\n\treturn errors.join(\"; \") || \"schema validation failed\";\n}\n\nfunction assertValidParams<TSchemaDef extends TSchema>(schema: TSchemaDef, params: Static<TSchemaDef>): void {\n\tif (Value.Check(schema, params)) {\n\t\treturn;\n\t}\n\tthrow new Error(`Structured output validation failed: ${formatValidationErrors(schema, params)}`);\n}\n\nfunction stringifyParams<TSchemaDef extends TSchema>(params: Static<TSchemaDef>): string {\n\ttry {\n\t\treturn JSON.stringify(params, null, 2);\n\t} catch (error) {\n\t\tthrow new Error(`Structured output must be JSON-serializable: ${error instanceof Error ? error.message : String(error)}`);\n\t}\n}\n\nexport function getStructuredOutputMetadataPath(outputPath: string): string {\n\tconst directory = path.dirname(outputPath);\n\tconst basename = path.basename(outputPath);\n\tif (basename === \"output.json\") {\n\t\treturn path.join(directory, \"output.meta.json\");\n\t}\n\tif (path.extname(basename) === \".json\") {\n\t\treturn path.join(directory, `${basename.slice(0, -\".json\".length)}.meta.json`);\n\t}\n\treturn `${outputPath}.meta.json`;\n}\n\nfunction createStructuredOutputCaptureMetadata(toolName: string, toolCallId: string): StructuredOutputCaptureMetadata {\n\treturn {\n\t\ttoolName,\n\t\ttoolCallId,\n\t\tsuccess: true,\n\t\tterminate: true,\n\t\tcapturedAt: new Date().toISOString(),\n\t};\n}\n\nasync function writePrivateJsonFile(filePath: string, serializedJson: string): Promise<void> {\n\tawait fs.mkdir(path.dirname(filePath), { recursive: true });\n\tawait fs.writeFile(filePath, serializedJson, { mode: 0o600 });\n\t// Re-apply the private mode after writing so pre-existing looser files are tightened too.\n\tawait fs.chmod(filePath, 0o600);\n}\n\nasync function writeCapturedOutput(\n\toutput: StructuredOutputFileCapture,\n\tserializedParams: string,\n\tmetadata: StructuredOutputCaptureMetadata,\n): Promise<void> {\n\ttry {\n\t\tawait writePrivateJsonFile(output.outputPath, serializedParams);\n\t\tawait writePrivateJsonFile(output.metadataPath ?? getStructuredOutputMetadataPath(output.outputPath), stringifyParams(metadata));\n\t} catch (error) {\n\t\tthrow new Error(`Failed to write structured output capture: ${error instanceof Error ? error.message : String(error)}`);\n\t}\n}\n\nexport function createStructuredOutputCapture<TValue>(): StructuredOutputCapture<TValue> {\n\treturn { value: undefined, called: false };\n}\n\nexport function createStructuredOutputTool<TSchemaDef extends TSchema = typeof genericStructuredOutputParameters>(\n\toptions: StructuredOutputToolOptions<TSchemaDef> = {},\n): ToolDefinition<TSchemaDef, Static<TSchemaDef>> {\n\tconst name = options.name ?? STRUCTURED_OUTPUT_TOOL_NAME;\n\tconst schema = (options.schema === undefined ? genericStructuredOutputParameters : options.schema) as TSchemaDef;\n\tassertStructuredOutputParameterSchema(schema, `${name} schema`);\n\n\tlet outputCalled = false;\n\tconst hasSingleRunSink = options.capture !== undefined || options.output !== undefined;\n\n\treturn defineTool({\n\t\tname,\n\t\tlabel: \"Structured Output\",\n\t\tdescription: \"Submit the final machine-readable structured output. This terminates the current agent turn.\",\n\t\tpromptSnippet: `Submit the final machine-readable answer as a terminating ${name} tool call`,\n\t\tpromptGuidelines: [\n\t\t\t`Use ${name} exactly once as your final action when the requested result should be machine-readable or schema-valid.`,\n\t\t\t\"Pass the schema fields directly as tool arguments; do not wrap them in `{ value: ... }` unless the schema explicitly defines a top-level `value` field.\",\n\t\t\t`Do not write prose after calling ${name}; the tool result is the final answer.`,\n\t\t],\n\t\tparameters: schema,\n\t\tmaxResultSizeChars: Infinity,\n\t\tstructuredOutput: true,\n\t\texecutionMode: \"sequential\",\n\t\tasync execute(toolCallId, params): Promise<AgentToolResult<Static<TSchemaDef>>> {\n\t\t\tassertValidParams(schema, params);\n\t\t\tif (hasSingleRunSink && (outputCalled || options.capture?.called)) {\n\t\t\t\tthrow new Error(`${name} was already called for this result contract.`);\n\t\t\t}\n\n\t\t\tconst serializedParams = stringifyParams(params);\n\t\t\tif (options.output) {\n\t\t\t\tawait writeCapturedOutput(options.output, serializedParams, createStructuredOutputCaptureMetadata(name, toolCallId));\n\t\t\t}\n\t\t\tif (options.capture) {\n\t\t\t\toptions.capture.value = params;\n\t\t\t\toptions.capture.called = true;\n\t\t\t}\n\t\t\toutputCalled = true;\n\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: serializedParams }],\n\t\t\t\tdetails: params,\n\t\t\t\tterminate: true,\n\t\t\t};\n\t\t},\n\t});\n}\n"]}
+{"version":3,"file":"structured-output.js","sourceRoot":"","sources":["../../../src/core/tools/structured-output.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport type { AgentToolResult } from \"@earendil-works/pi-agent-core\";\nimport { type Static, type TSchema } from \"typebox\";\nimport { defineTool, type ToolDefinition } from \"../extensions/types.ts\";\n\nexport const STRUCTURED_OUTPUT_TOOL_NAME = \"structured_output\";\n\nexport type JsonPrimitive = string | number | boolean | null;\nexport type JsonValue = JsonPrimitive | JsonObject | JsonValue[];\nexport type JsonObject = { readonly [key: string]: JsonValue };\n\nexport interface StructuredOutputCapture<TValue = unknown> {\n\tvalue: TValue | undefined;\n\tcalled: boolean;\n}\n\nexport interface StructuredOutputFileCapture {\n\toutputPath: string;\n}\n\nexport interface StructuredOutputToolOptions<TSchemaDef extends TSchema> {\n\t/** Tool parameter schema. */\n\tschema: TSchemaDef;\n\t/** In-process result sink for SDK and workflow callers. */\n\tcapture?: StructuredOutputCapture<Static<TSchemaDef>>;\n\t/** Cross-process result sink for subagent child runtimes. */\n\toutput?: StructuredOutputFileCapture;\n\t/** Tool name. Defaults to `structured_output`. */\n\tname?: string;\n}\n\nfunction stringifyParams<TSchemaDef extends TSchema>(params: Static<TSchemaDef>): string {\n\ttry {\n\t\treturn JSON.stringify(params, null, 2);\n\t} catch (error) {\n\t\tthrow new Error(`Structured output must be JSON-serializable: ${error instanceof Error ? error.message : String(error)}`);\n\t}\n}\n\nasync function writePrivateJsonFile(filePath: string, serializedJson: string): Promise<void> {\n\tawait fs.mkdir(path.dirname(filePath), { recursive: true });\n\tawait fs.writeFile(filePath, serializedJson, { mode: 0o600 });\n\t// Re-apply the private mode after writing so pre-existing looser files are tightened too.\n\tawait fs.chmod(filePath, 0o600);\n}\n\nasync function writeCapturedOutput(output: StructuredOutputFileCapture, serializedParams: string): Promise<void> {\n\ttry {\n\t\tawait writePrivateJsonFile(output.outputPath, serializedParams);\n\t} catch (error) {\n\t\tthrow new Error(`Failed to write structured output capture: ${error instanceof Error ? error.message : String(error)}`);\n\t}\n}\n\nexport function createStructuredOutputCapture<TValue = unknown>(): StructuredOutputCapture<TValue> {\n\treturn { value: undefined, called: false };\n}\n\nexport function createStructuredOutputTool<TSchemaDef extends TSchema>(\n\toptions: StructuredOutputToolOptions<TSchemaDef>,\n): ToolDefinition<TSchemaDef, Static<TSchemaDef>> {\n\tconst name = options.name ?? STRUCTURED_OUTPUT_TOOL_NAME;\n\n\treturn defineTool({\n\t\tname,\n\t\tlabel: \"Structured Output\",\n\t\tdescription: \"Return the final machine-readable result.\",\n\t\tpromptSnippet: \"Return final machine-readable output\",\n\t\tpromptGuidelines: [\n\t\t\t`${name} is the final machine-readable result channel; call ${name} exactly once when done.`,\n\t\t\t`Do not write a prose final answer after calling ${name}.`,\n\t\t],\n\t\tparameters: options.schema,\n\t\tmaxResultSizeChars: Infinity,\n\t\tstructuredOutput: true,\n\t\tasync execute(_toolCallId, params): Promise<AgentToolResult<Static<TSchemaDef>>> {\n\t\t\tconst serializedParams = stringifyParams(params);\n\t\t\tif (options.output) {\n\t\t\t\tawait writeCapturedOutput(options.output, serializedParams);\n\t\t\t}\n\t\t\tif (options.capture) {\n\t\t\t\toptions.capture.value = params;\n\t\t\t\toptions.capture.called = true;\n\t\t\t}\n\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: serializedParams }],\n\t\t\t\tdetails: params,\n\t\t\t\tterminate: true,\n\t\t\t};\n\t\t},\n\t});\n}\n"]}

package/dist/core/tools/todos.d.ts

@@ -30,6 +30,7 @@ type TodoToolDetails = {
     todo?: TodoRecord;
     error?: string;
 };
+export declare const DEFAULT_PROMPT_GUIDANCE: string[];
 export declare function createTodoToolDefinition(cwd?: string): ToolDefinition<typeof TodoParams, TodoToolDetails>;
 export {};
 //# sourceMappingURL=todos.d.ts.map

package/dist/core/tools/todos.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"todos.d.ts","sourceRoot":"","sources":["../../../src/core/tools/todos.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,OAAO,KAAK,EAAoB,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAU/E,UAAU,eAAe;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,UAAU,UAAW,SAAQ,eAAe;IAC3C,IAAI,EAAE,MAAM,CAAC;CACb;AASD,QAAA,MAAM,UAAU;;;;;;;;EAsBd,CAAC;AAaH,KAAK,eAAe,GACjB;IACA,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC;IAC5B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CACd,GACD;IACA,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IAChF,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAymBL,wBAAgB,wBAAwB,CACvC,GAAG,GAAE,MAAsB,GACzB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,CAAC,CA4WpD","sourcesContent":["/**\n * This tool stores todo items as files under <todo-dir> (defaults to\n * <CONFIG_DIR_NAME>/todos, or the path in <APP_NAME>_TODO_PATH).  Each todo is\n * a standalone markdown file named <id>.md and an optional <id>.lock file is\n * used while a session is editing it.\n *\n * File format in <CONFIG_DIR_NAME>/todos:\n * - The file starts with a JSON object (not YAML) containing the front matter:\n *   { id, title, tags, status, created_at, assigned_to_session }\n * - After the JSON block comes optional markdown body text separated by a blank line.\n * - Example:\n *   {\n *     \"id\": \"deadbeef\",\n *     \"title\": \"Add tests\",\n *     \"tags\": [\"qa\"],\n *     \"status\": \"open\",\n *     \"created_at\": \"2026-01-25T17:00:00.000Z\",\n *     \"assigned_to_session\": \"session.json\"\n *   }\n *\n *   Notes about the work go here.\n */\nimport { StringEnum } from \"@earendil-works/pi-ai\";\nimport { Text } from \"@earendil-works/pi-tui\";\nimport crypto from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { Type } from \"typebox\";\nimport { APP_NAME, CONFIG_DIR_NAME, getEnvValue } from \"../../config.ts\";\nimport type { ExtensionContext, ToolDefinition } from \"../extensions/types.ts\";\nimport { keyHint } from \"../../modes/interactive/components/keybinding-hints.ts\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\n\nconst TODO_DIR_NAME = `${CONFIG_DIR_NAME}/todos`;\nconst TODO_PATH_ENV = `${APP_NAME.toUpperCase()}_TODO_PATH`;\nconst TODO_ID_PREFIX = \"TODO-\";\nconst TODO_ID_PATTERN = /^[a-f0-9]{8}$/i;\nconst LOCK_TTL_MS = 30 * 60 * 1000;\n\ninterface TodoFrontMatter {\n\tid: string;\n\ttitle: string;\n\ttags: string[];\n\tstatus: string;\n\tcreated_at: string;\n\tassigned_to_session?: string;\n}\n\ninterface TodoRecord extends TodoFrontMatter {\n\tbody: string;\n}\n\ninterface LockInfo {\n\tid: string;\n\tpid: number;\n\tsession?: string | null;\n\tcreated_at: string;\n}\n\nconst TodoParams = Type.Object({\n\taction: StringEnum([\n\t\t\"list\",\n\t\t\"list-all\",\n\t\t\"get\",\n\t\t\"create\",\n\t\t\"update\",\n\t\t\"append\",\n\t\t\"delete\",\n\t\t\"claim\",\n\t\t\"release\",\n\t] as const),\n\tid: Type.Optional(Type.String({ description: \"Todo id (TODO-<hex> or raw hex filename)\" })),\n\ttitle: Type.Optional(Type.String({ description: \"Short summary shown in lists\" })),\n\tstatus: Type.Optional(Type.String({ description: \"Todo status\" })),\n\ttags: Type.Optional(Type.Array(Type.String({ description: \"Todo tag\" }))),\n\tbody: Type.Optional(\n\t\tType.String({\n\t\t\tdescription: \"Long-form details (markdown). Update replaces; append adds.\",\n\t\t}),\n\t),\n\tforce: Type.Optional(Type.Boolean({ description: \"Override another session's assignment\" })),\n});\n\ntype TodoAction =\n\t| \"list\"\n\t| \"list-all\"\n\t| \"get\"\n\t| \"create\"\n\t| \"update\"\n\t| \"append\"\n\t| \"delete\"\n\t| \"claim\"\n\t| \"release\";\n\ntype TodoToolDetails =\n\t| {\n\t\t\taction: \"list\" | \"list-all\";\n\t\t\ttodos: TodoFrontMatter[];\n\t\t\tcurrentSessionId?: string;\n\t\t\terror?: string;\n\t  }\n\t| {\n\t\t\taction: \"get\" | \"create\" | \"update\" | \"append\" | \"delete\" | \"claim\" | \"release\";\n\t\t\ttodo?: TodoRecord;\n\t\t\terror?: string;\n\t  };\n\nfunction formatTodoId(id: string): string {\n\treturn `${TODO_ID_PREFIX}${id}`;\n}\n\nfunction normalizeTodoId(id: string): string {\n\tlet trimmed = id.trim();\n\tif (trimmed.startsWith(\"#\")) {\n\t\ttrimmed = trimmed.slice(1);\n\t}\n\tif (trimmed.toUpperCase().startsWith(TODO_ID_PREFIX)) {\n\t\ttrimmed = trimmed.slice(TODO_ID_PREFIX.length);\n\t}\n\treturn trimmed;\n}\n\nfunction validateTodoId(id: string): { id: string } | { error: string } {\n\tconst normalized = normalizeTodoId(id);\n\tif (!normalized || !TODO_ID_PATTERN.test(normalized)) {\n\t\treturn { error: \"Invalid todo id. Expected TODO-<hex>.\" };\n\t}\n\treturn { id: normalized.toLowerCase() };\n}\n\nfunction displayTodoId(id: string): string {\n\treturn formatTodoId(normalizeTodoId(id));\n}\n\nfunction isTodoClosed(status: string): boolean {\n\treturn [\"closed\", \"done\"].includes(status.toLowerCase());\n}\n\nfunction clearAssignmentIfClosed(todo: TodoFrontMatter): void {\n\tif (isTodoClosed(getTodoStatus(todo))) {\n\t\ttodo.assigned_to_session = undefined;\n\t}\n}\n\nfunction sortTodos(todos: TodoFrontMatter[]): TodoFrontMatter[] {\n\treturn [...todos].sort((a, b) => {\n\t\tconst aClosed = isTodoClosed(a.status);\n\t\tconst bClosed = isTodoClosed(b.status);\n\t\tif (aClosed !== bClosed) return aClosed ? 1 : -1;\n\t\tconst aAssigned = !aClosed && Boolean(a.assigned_to_session);\n\t\tconst bAssigned = !bClosed && Boolean(b.assigned_to_session);\n\t\tif (aAssigned !== bAssigned) return aAssigned ? -1 : 1;\n\t\treturn (a.created_at || \"\").localeCompare(b.created_at || \"\");\n\t});\n}\n\nfunction getTodosDir(cwd: string): string {\n\tconst overridePath = getEnvValue(TODO_PATH_ENV);\n\tif (overridePath && overridePath.trim()) {\n\t\treturn path.resolve(cwd, overridePath.trim());\n\t}\n\treturn path.resolve(cwd, TODO_DIR_NAME);\n}\n\nfunction getTodosDirLabel(cwd: string): string {\n\tconst overridePath = getEnvValue(TODO_PATH_ENV);\n\tif (overridePath && overridePath.trim()) {\n\t\treturn path.resolve(cwd, overridePath.trim());\n\t}\n\treturn TODO_DIR_NAME;\n}\n\nfunction getTodoPath(todosDir: string, id: string): string {\n\treturn path.join(todosDir, `${id}.md`);\n}\n\nfunction getLockPath(todosDir: string, id: string): string {\n\treturn path.join(todosDir, `${id}.lock`);\n}\n\nfunction parseFrontMatter(text: string, idFallback: string): TodoFrontMatter {\n\tconst data: TodoFrontMatter = {\n\t\tid: idFallback,\n\t\ttitle: \"\",\n\t\ttags: [],\n\t\tstatus: \"open\",\n\t\tcreated_at: \"\",\n\t\tassigned_to_session: undefined,\n\t};\n\n\tconst trimmed = text.trim();\n\tif (!trimmed) return data;\n\n\ttry {\n\t\tconst parsed = JSON.parse(trimmed) as Partial<TodoFrontMatter> | null;\n\t\tif (!parsed || typeof parsed !== \"object\") return data;\n\t\tif (typeof parsed.id === \"string\" && parsed.id) data.id = parsed.id;\n\t\tif (typeof parsed.title === \"string\") data.title = parsed.title;\n\t\tif (typeof parsed.status === \"string\" && parsed.status) data.status = parsed.status;\n\t\tif (typeof parsed.created_at === \"string\") data.created_at = parsed.created_at;\n\t\tif (\n\t\t\ttypeof parsed.assigned_to_session === \"string\" &&\n\t\t\tparsed.assigned_to_session.trim()\n\t\t) {\n\t\t\tdata.assigned_to_session = parsed.assigned_to_session;\n\t\t}\n\t\tif (Array.isArray(parsed.tags)) {\n\t\t\tdata.tags = parsed.tags.filter((tag): tag is string => typeof tag === \"string\");\n\t\t}\n\t} catch {\n\t\treturn data;\n\t}\n\n\treturn data;\n}\n\nfunction findJsonObjectEnd(content: string): number {\n\tlet depth = 0;\n\tlet inString = false;\n\tlet escaped = false;\n\n\tfor (let i = 0; i < content.length; i += 1) {\n\t\tconst char = content[i];\n\n\t\tif (inString) {\n\t\t\tif (escaped) {\n\t\t\t\tescaped = false;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (char === \"\\\\\") {\n\t\t\t\tescaped = true;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (char === '\"') {\n\t\t\t\tinString = false;\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (char === '\"') {\n\t\t\tinString = true;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (char === \"{\") {\n\t\t\tdepth += 1;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (char === \"}\") {\n\t\t\tdepth -= 1;\n\t\t\tif (depth === 0) return i;\n\t\t}\n\t}\n\n\treturn -1;\n}\n\nfunction splitFrontMatter(content: string): { frontMatter: string; body: string } {\n\tif (!content.startsWith(\"{\")) {\n\t\treturn { frontMatter: \"\", body: content };\n\t}\n\n\tconst endIndex = findJsonObjectEnd(content);\n\tif (endIndex === -1) {\n\t\treturn { frontMatter: \"\", body: content };\n\t}\n\n\tconst frontMatter = content.slice(0, endIndex + 1);\n\tconst body = content.slice(endIndex + 1).replace(/^\\r?\\n+/, \"\");\n\treturn { frontMatter, body };\n}\n\nfunction parseTodoContent(content: string, idFallback: string): TodoRecord {\n\tconst { frontMatter, body } = splitFrontMatter(content);\n\tconst parsed = parseFrontMatter(frontMatter, idFallback);\n\treturn {\n\t\tid: idFallback,\n\t\ttitle: parsed.title,\n\t\ttags: parsed.tags ?? [],\n\t\tstatus: parsed.status,\n\t\tcreated_at: parsed.created_at,\n\t\tassigned_to_session: parsed.assigned_to_session,\n\t\tbody: body ?? \"\",\n\t};\n}\n\nfunction serializeTodo(todo: TodoRecord): string {\n\tconst frontMatter = JSON.stringify(\n\t\t{\n\t\t\tid: todo.id,\n\t\t\ttitle: todo.title,\n\t\t\ttags: todo.tags ?? [],\n\t\t\tstatus: todo.status,\n\t\t\tcreated_at: todo.created_at,\n\t\t\tassigned_to_session: todo.assigned_to_session || undefined,\n\t\t},\n\t\tnull,\n\t\t2,\n\t);\n\n\tconst body = todo.body ?? \"\";\n\tconst trimmedBody = body.replace(/^\\n+/, \"\").replace(/\\s+$/, \"\");\n\tif (!trimmedBody) return `${frontMatter}\\n`;\n\treturn `${frontMatter}\\n\\n${trimmedBody}\\n`;\n}\n\nasync function ensureTodosDir(todosDir: string) {\n\tawait fs.mkdir(todosDir, { recursive: true });\n}\n\nasync function readTodoFile(filePath: string, idFallback: string): Promise<TodoRecord> {\n\tconst content = await fs.readFile(filePath, \"utf8\");\n\treturn parseTodoContent(content, idFallback);\n}\n\nasync function writeTodoFile(filePath: string, todo: TodoRecord) {\n\tawait fs.writeFile(filePath, serializeTodo(todo), \"utf8\");\n}\n\nasync function generateTodoId(todosDir: string): Promise<string> {\n\tfor (let attempt = 0; attempt < 10; attempt += 1) {\n\t\tconst id = crypto.randomBytes(4).toString(\"hex\");\n\t\tconst todoPath = getTodoPath(todosDir, id);\n\t\tif (!existsSync(todoPath)) return id;\n\t}\n\tthrow new Error(\"Failed to generate unique todo id\");\n}\n\nasync function readLockInfo(lockPath: string): Promise<LockInfo | null> {\n\ttry {\n\t\tconst raw = await fs.readFile(lockPath, \"utf8\");\n\t\treturn JSON.parse(raw) as LockInfo;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nasync function acquireLock(\n\ttodosDir: string,\n\tid: string,\n\tctx: ExtensionContext,\n): Promise<(() => Promise<void>) | { error: string }> {\n\tconst lockPath = getLockPath(todosDir, id);\n\tconst now = Date.now();\n\tconst session = ctx.sessionManager.getSessionFile();\n\n\tfor (let attempt = 0; attempt < 2; attempt += 1) {\n\t\ttry {\n\t\t\tconst handle = await fs.open(lockPath, \"wx\");\n\t\t\tconst info: LockInfo = {\n\t\t\t\tid,\n\t\t\t\tpid: process.pid,\n\t\t\t\tsession,\n\t\t\t\tcreated_at: new Date(now).toISOString(),\n\t\t\t};\n\t\t\tawait handle.writeFile(JSON.stringify(info, null, 2), \"utf8\");\n\t\t\tawait handle.close();\n\t\t\treturn async () => {\n\t\t\t\ttry {\n\t\t\t\t\tawait fs.unlink(lockPath);\n\t\t\t\t} catch {\n\t\t\t\t\t// ignore\n\t\t\t\t}\n\t\t\t};\n\t\t} catch (error) {\n\t\t\tconst fsError = error as { code?: string; message?: string };\n\t\t\tif (fsError.code !== \"EEXIST\") {\n\t\t\t\treturn {\n\t\t\t\t\terror: `Failed to acquire lock: ${fsError.message ?? \"unknown error\"}`,\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst stats = await fs.stat(lockPath).catch(() => null);\n\t\t\tconst lockAge = stats ? now - stats.mtimeMs : LOCK_TTL_MS + 1;\n\t\t\tif (lockAge <= LOCK_TTL_MS) {\n\t\t\t\tconst info = await readLockInfo(lockPath);\n\t\t\t\tconst owner = info?.session ? ` (session ${info.session})` : \"\";\n\t\t\t\treturn {\n\t\t\t\t\terror: `Todo ${displayTodoId(id)} is locked${owner}. Try again later.`,\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (!ctx.hasUI) {\n\t\t\t\treturn {\n\t\t\t\t\terror: `Todo ${displayTodoId(id)} lock is stale; rerun in interactive mode to steal it.`,\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst ok = await ctx.ui.confirm(\n\t\t\t\t\"Todo locked\",\n\t\t\t\t`Todo ${displayTodoId(id)} appears locked. Steal the lock?`,\n\t\t\t);\n\t\t\tif (!ok) {\n\t\t\t\treturn { error: `Todo ${displayTodoId(id)} remains locked.` };\n\t\t\t}\n\t\t\tawait fs.unlink(lockPath).catch(() => undefined);\n\t\t}\n\t}\n\n\treturn { error: `Failed to acquire lock for todo ${displayTodoId(id)}.` };\n}\n\nasync function withTodoLock<T>(\n\ttodosDir: string,\n\tid: string,\n\tctx: ExtensionContext,\n\tfn: () => Promise<T>,\n): Promise<T | { error: string }> {\n\tconst lock = await acquireLock(todosDir, id, ctx);\n\tif (typeof lock === \"object\" && \"error\" in lock) return lock;\n\ttry {\n\t\treturn await fn();\n\t} finally {\n\t\tawait lock();\n\t}\n}\n\nasync function listTodos(todosDir: string): Promise<TodoFrontMatter[]> {\n\tlet entries: string[] = [];\n\ttry {\n\t\tentries = await fs.readdir(todosDir);\n\t} catch {\n\t\treturn [];\n\t}\n\n\tconst todos: TodoFrontMatter[] = [];\n\tfor (const entry of entries) {\n\t\tif (!entry.endsWith(\".md\")) continue;\n\t\tconst id = entry.slice(0, -3);\n\t\tconst filePath = path.join(todosDir, entry);\n\t\ttry {\n\t\t\tconst content = await fs.readFile(filePath, \"utf8\");\n\t\t\tconst { frontMatter } = splitFrontMatter(content);\n\t\t\tconst parsed = parseFrontMatter(frontMatter, id);\n\t\t\ttodos.push({\n\t\t\t\tid,\n\t\t\t\ttitle: parsed.title,\n\t\t\t\ttags: parsed.tags ?? [],\n\t\t\t\tstatus: parsed.status,\n\t\t\t\tcreated_at: parsed.created_at,\n\t\t\t\tassigned_to_session: parsed.assigned_to_session,\n\t\t\t});\n\t\t} catch {\n\t\t\t// ignore unreadable todo\n\t\t}\n\t}\n\n\treturn sortTodos(todos);\n}\n\nfunction getTodoTitle(todo: TodoFrontMatter): string {\n\treturn todo.title || \"(untitled)\";\n}\n\nfunction getTodoStatus(todo: TodoFrontMatter): string {\n\treturn todo.status || \"open\";\n}\n\nfunction renderAssignmentSuffix(\n\ttheme: Theme,\n\ttodo: TodoFrontMatter,\n\tcurrentSessionId?: string,\n): string {\n\tif (!todo.assigned_to_session) return \"\";\n\tconst isCurrent = todo.assigned_to_session === currentSessionId;\n\tconst color = isCurrent ? \"success\" : \"dim\";\n\tconst suffix = isCurrent ? \", current\" : \"\";\n\treturn theme.fg(color, ` (assigned: ${todo.assigned_to_session}${suffix})`);\n}\n\nfunction splitTodosByAssignment(todos: TodoFrontMatter[]): {\n\tassignedTodos: TodoFrontMatter[];\n\topenTodos: TodoFrontMatter[];\n\tclosedTodos: TodoFrontMatter[];\n} {\n\tconst assignedTodos: TodoFrontMatter[] = [];\n\tconst openTodos: TodoFrontMatter[] = [];\n\tconst closedTodos: TodoFrontMatter[] = [];\n\tfor (const todo of todos) {\n\t\tif (isTodoClosed(getTodoStatus(todo))) {\n\t\t\tclosedTodos.push(todo);\n\t\t\tcontinue;\n\t\t}\n\t\tif (todo.assigned_to_session) {\n\t\t\tassignedTodos.push(todo);\n\t\t} else {\n\t\t\topenTodos.push(todo);\n\t\t}\n\t}\n\treturn { assignedTodos, openTodos, closedTodos };\n}\n\nfunction serializeTodoForAgent(todo: TodoRecord): string {\n\tconst payload = { ...todo, id: formatTodoId(todo.id) };\n\treturn JSON.stringify(payload, null, 2);\n}\n\nfunction serializeTodoListForAgent(todos: TodoFrontMatter[]): string {\n\tconst { assignedTodos, openTodos, closedTodos } = splitTodosByAssignment(todos);\n\tconst mapTodo = (todo: TodoFrontMatter) => ({\n\t\t...todo,\n\t\tid: formatTodoId(todo.id),\n\t});\n\treturn JSON.stringify(\n\t\t{\n\t\t\tassigned: assignedTodos.map(mapTodo),\n\t\t\topen: openTodos.map(mapTodo),\n\t\t\tclosed: closedTodos.map(mapTodo),\n\t\t},\n\t\tnull,\n\t\t2,\n\t);\n}\n\nfunction renderTodoHeading(\n\ttheme: Theme,\n\ttodo: TodoFrontMatter,\n\tcurrentSessionId?: string,\n): string {\n\tconst closed = isTodoClosed(getTodoStatus(todo));\n\tconst titleColor = closed ? \"dim\" : \"text\";\n\tconst tagText = todo.tags.length ? theme.fg(\"dim\", ` [${todo.tags.join(\", \")}]`) : \"\";\n\tconst assignmentText = renderAssignmentSuffix(theme, todo, currentSessionId);\n\treturn (\n\t\ttheme.fg(\"accent\", formatTodoId(todo.id)) +\n\t\t\" \" +\n\t\ttheme.fg(titleColor, getTodoTitle(todo)) +\n\t\ttagText +\n\t\tassignmentText\n\t);\n}\n\nfunction renderTodoList(\n\ttheme: Theme,\n\ttodos: TodoFrontMatter[],\n\texpanded: boolean,\n\tcurrentSessionId?: string,\n): string {\n\tif (!todos.length) return theme.fg(\"dim\", \"No todos\");\n\n\tconst { assignedTodos, openTodos, closedTodos } = splitTodosByAssignment(todos);\n\tconst lines: string[] = [];\n\tconst pushSection = (label: string, sectionTodos: TodoFrontMatter[]) => {\n\t\tlines.push(theme.fg(\"muted\", `${label} (${sectionTodos.length})`));\n\t\tif (!sectionTodos.length) {\n\t\t\tlines.push(theme.fg(\"dim\", \"  none\"));\n\t\t\treturn;\n\t\t}\n\t\tconst maxItems = expanded ? sectionTodos.length : Math.min(sectionTodos.length, 3);\n\t\tfor (let i = 0; i < maxItems; i++) {\n\t\t\tlines.push(`  ${renderTodoHeading(theme, sectionTodos[i], currentSessionId)}`);\n\t\t}\n\t\tif (!expanded && sectionTodos.length > maxItems) {\n\t\t\tlines.push(theme.fg(\"dim\", `  ... ${sectionTodos.length - maxItems} more`));\n\t\t}\n\t};\n\n\tconst sections: Array<{ label: string; todos: TodoFrontMatter[] }> = [\n\t\t{ label: \"Assigned todos\", todos: assignedTodos },\n\t\t{ label: \"Open todos\", todos: openTodos },\n\t\t{ label: \"Closed todos\", todos: closedTodos },\n\t];\n\n\tsections.forEach((section, index) => {\n\t\tif (index > 0) lines.push(\"\");\n\t\tpushSection(section.label, section.todos);\n\t});\n\n\treturn lines.join(\"\\n\");\n}\n\nfunction renderTodoDetail(theme: Theme, todo: TodoRecord, expanded: boolean): string {\n\tconst summary = renderTodoHeading(theme, todo);\n\tif (!expanded) return summary;\n\n\tconst tags = todo.tags.length ? todo.tags.join(\", \") : \"none\";\n\tconst createdAt = todo.created_at || \"unknown\";\n\tconst bodyText = todo.body?.trim() ? todo.body.trim() : \"No details yet.\";\n\tconst bodyLines = bodyText.split(\"\\n\");\n\n\tconst lines = [\n\t\tsummary,\n\t\ttheme.fg(\"muted\", `Status: ${getTodoStatus(todo)}`),\n\t\ttheme.fg(\"muted\", `Tags: ${tags}`),\n\t\ttheme.fg(\"muted\", `Created: ${createdAt}`),\n\t\t\"\",\n\t\ttheme.fg(\"muted\", \"Body:\"),\n\t\t...bodyLines.map((line) => theme.fg(\"text\", `  ${line}`)),\n\t];\n\n\treturn lines.join(\"\\n\");\n}\n\nfunction appendExpandHint(theme: Theme, text: string): string {\n\treturn `${text}\\n${theme.fg(\"dim\", `(${keyHint(\"app.tools.expand\", \"Expand\")})`)}`;\n}\n\nasync function ensureTodoExists(filePath: string, id: string): Promise<TodoRecord | null> {\n\tif (!existsSync(filePath)) return null;\n\treturn readTodoFile(filePath, id);\n}\n\nasync function appendTodoBody(\n\tfilePath: string,\n\ttodo: TodoRecord,\n\ttext: string,\n): Promise<TodoRecord> {\n\tconst spacer = todo.body.trim().length ? \"\\n\\n\" : \"\";\n\ttodo.body = `${todo.body.replace(/\\s+$/, \"\")}${spacer}${text.trim()}\\n`;\n\tawait writeTodoFile(filePath, todo);\n\treturn todo;\n}\n\nasync function claimTodoAssignment(\n\ttodosDir: string,\n\tid: string,\n\tctx: ExtensionContext,\n\tforce = false,\n): Promise<TodoRecord | { error: string }> {\n\tconst validated = validateTodoId(id);\n\tif (\"error\" in validated) {\n\t\treturn { error: validated.error };\n\t}\n\tconst normalizedId = validated.id;\n\tconst filePath = getTodoPath(todosDir, normalizedId);\n\tif (!existsSync(filePath)) {\n\t\treturn { error: `Todo ${displayTodoId(id)} not found` };\n\t}\n\tconst sessionId = ctx.sessionManager.getSessionId();\n\tconst result = await withTodoLock(todosDir, normalizedId, ctx, async () => {\n\t\tconst existing = await ensureTodoExists(filePath, normalizedId);\n\t\tif (!existing) return { error: `Todo ${displayTodoId(id)} not found` } as const;\n\t\tif (isTodoClosed(existing.status)) {\n\t\t\treturn { error: `Todo ${displayTodoId(id)} is closed` } as const;\n\t\t}\n\t\tconst assigned = existing.assigned_to_session;\n\t\tif (assigned && assigned !== sessionId && !force) {\n\t\t\treturn {\n\t\t\t\terror: `Todo ${displayTodoId(id)} is already assigned to session ${assigned}. Use force to override.`,\n\t\t\t} as const;\n\t\t}\n\t\tif (assigned !== sessionId) {\n\t\t\texisting.assigned_to_session = sessionId;\n\t\t\tawait writeTodoFile(filePath, existing);\n\t\t}\n\t\treturn existing;\n\t});\n\n\tif (typeof result === \"object\" && \"error\" in result) {\n\t\treturn { error: result.error };\n\t}\n\n\treturn result;\n}\n\nasync function releaseTodoAssignment(\n\ttodosDir: string,\n\tid: string,\n\tctx: ExtensionContext,\n\tforce = false,\n): Promise<TodoRecord | { error: string }> {\n\tconst validated = validateTodoId(id);\n\tif (\"error\" in validated) {\n\t\treturn { error: validated.error };\n\t}\n\tconst normalizedId = validated.id;\n\tconst filePath = getTodoPath(todosDir, normalizedId);\n\tif (!existsSync(filePath)) {\n\t\treturn { error: `Todo ${displayTodoId(id)} not found` };\n\t}\n\tconst sessionId = ctx.sessionManager.getSessionId();\n\tconst result = await withTodoLock(todosDir, normalizedId, ctx, async () => {\n\t\tconst existing = await ensureTodoExists(filePath, normalizedId);\n\t\tif (!existing) return { error: `Todo ${displayTodoId(id)} not found` } as const;\n\t\tconst assigned = existing.assigned_to_session;\n\t\tif (!assigned) {\n\t\t\treturn existing;\n\t\t}\n\t\tif (assigned !== sessionId && !force) {\n\t\t\treturn {\n\t\t\t\terror: `Todo ${displayTodoId(id)} is assigned to session ${assigned}. Use force to release.`,\n\t\t\t} as const;\n\t\t}\n\t\texisting.assigned_to_session = undefined;\n\t\tawait writeTodoFile(filePath, existing);\n\t\treturn existing;\n\t});\n\n\tif (typeof result === \"object\" && \"error\" in result) {\n\t\treturn { error: result.error };\n\t}\n\n\treturn result;\n}\n\nasync function deleteTodo(\n\ttodosDir: string,\n\tid: string,\n\tctx: ExtensionContext,\n): Promise<TodoRecord | { error: string }> {\n\tconst validated = validateTodoId(id);\n\tif (\"error\" in validated) {\n\t\treturn { error: validated.error };\n\t}\n\tconst normalizedId = validated.id;\n\tconst filePath = getTodoPath(todosDir, normalizedId);\n\tif (!existsSync(filePath)) {\n\t\treturn { error: `Todo ${displayTodoId(id)} not found` };\n\t}\n\n\tconst result = await withTodoLock(todosDir, normalizedId, ctx, async () => {\n\t\tconst existing = await ensureTodoExists(filePath, normalizedId);\n\t\tif (!existing) return { error: `Todo ${displayTodoId(id)} not found` } as const;\n\t\tawait fs.unlink(filePath);\n\t\treturn existing;\n\t});\n\n\tif (typeof result === \"object\" && \"error\" in result) {\n\t\treturn { error: result.error };\n\t}\n\n\treturn result;\n}\n\nexport function createTodoToolDefinition(\n\tcwd: string = process.cwd(),\n): ToolDefinition<typeof TodoParams, TodoToolDetails> {\n\tconst todosDirLabel = getTodosDirLabel(cwd);\n\n\treturn {\n\t\tname: \"todo\",\n\t\tlabel: \"Todo\",\n\t\tdescription:\n\t\t\t`Manage file-based todos in ${todosDirLabel} (list, list-all, get, create, update, append, delete, claim, release). ` +\n\t\t\t\"Title is the short summary; body is long-form markdown notes (update replaces, append adds). \" +\n\t\t\t\"Todo ids are shown as TODO-<hex>; id parameters accept TODO-<hex> or the raw hex filename. \" +\n\t\t\t\"Claim tasks before working on them to avoid conflicts, and close them when complete.\",\n\t\tparameters: TodoParams,\n\n\t\tasync execute(_toolCallId, params, _signal, _onUpdate, ctx) {\n\t\t\tconst todosDir = getTodosDir(ctx.cwd);\n\t\t\tconst action: TodoAction = params.action;\n\n\t\t\tswitch (action) {\n\t\t\t\tcase \"list\": {\n\t\t\t\t\tconst todos = await listTodos(todosDir);\n\t\t\t\t\tconst { assignedTodos, openTodos } = splitTodosByAssignment(todos);\n\t\t\t\t\tconst listedTodos = [...assignedTodos, ...openTodos];\n\t\t\t\t\tconst currentSessionId = ctx.sessionManager.getSessionId();\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoListForAgent(listedTodos) }],\n\t\t\t\t\t\tdetails: { action: \"list\", todos: listedTodos, currentSessionId },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"list-all\": {\n\t\t\t\t\tconst todos = await listTodos(todosDir);\n\t\t\t\t\tconst currentSessionId = ctx.sessionManager.getSessionId();\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoListForAgent(todos) }],\n\t\t\t\t\t\tdetails: { action: \"list-all\", todos, currentSessionId },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"get\": {\n\t\t\t\t\tif (!params.id) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: id required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"get\", error: \"id required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst validated = validateTodoId(params.id);\n\t\t\t\t\tif (\"error\" in validated) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: validated.error }],\n\t\t\t\t\t\t\tdetails: { action: \"get\", error: validated.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst normalizedId = validated.id;\n\t\t\t\t\tconst displayId = formatTodoId(normalizedId);\n\t\t\t\t\tconst filePath = getTodoPath(todosDir, normalizedId);\n\t\t\t\t\tconst todo = await ensureTodoExists(filePath, normalizedId);\n\t\t\t\t\tif (!todo) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: `Todo ${displayId} not found` }],\n\t\t\t\t\t\t\tdetails: { action: \"get\", error: \"not found\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoForAgent(todo) }],\n\t\t\t\t\t\tdetails: { action: \"get\", todo },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"create\": {\n\t\t\t\t\tif (!params.title) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: title required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"create\", error: \"title required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tawait ensureTodosDir(todosDir);\n\t\t\t\t\tconst id = await generateTodoId(todosDir);\n\t\t\t\t\tconst filePath = getTodoPath(todosDir, id);\n\t\t\t\t\tconst todo: TodoRecord = {\n\t\t\t\t\t\tid,\n\t\t\t\t\t\ttitle: params.title,\n\t\t\t\t\t\ttags: params.tags ?? [],\n\t\t\t\t\t\tstatus: params.status ?? \"open\",\n\t\t\t\t\t\tcreated_at: new Date().toISOString(),\n\t\t\t\t\t\tbody: params.body ?? \"\",\n\t\t\t\t\t};\n\n\t\t\t\t\tconst result = await withTodoLock(todosDir, id, ctx, async () => {\n\t\t\t\t\t\tawait writeTodoFile(filePath, todo);\n\t\t\t\t\t\treturn todo;\n\t\t\t\t\t});\n\n\t\t\t\t\tif (typeof result === \"object\" && \"error\" in result) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: result.error }],\n\t\t\t\t\t\t\tdetails: { action: \"create\", error: result.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoForAgent(todo) }],\n\t\t\t\t\t\tdetails: { action: \"create\", todo },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"update\": {\n\t\t\t\t\tif (!params.id) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: id required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"update\", error: \"id required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst validated = validateTodoId(params.id);\n\t\t\t\t\tif (\"error\" in validated) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: validated.error }],\n\t\t\t\t\t\t\tdetails: { action: \"update\", error: validated.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst normalizedId = validated.id;\n\t\t\t\t\tconst displayId = formatTodoId(normalizedId);\n\t\t\t\t\tconst filePath = getTodoPath(todosDir, normalizedId);\n\t\t\t\t\tif (!existsSync(filePath)) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: `Todo ${displayId} not found` }],\n\t\t\t\t\t\t\tdetails: { action: \"update\", error: \"not found\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst result = await withTodoLock(todosDir, normalizedId, ctx, async () => {\n\t\t\t\t\t\tconst existing = await ensureTodoExists(filePath, normalizedId);\n\t\t\t\t\t\tif (!existing) return { error: `Todo ${displayId} not found` } as const;\n\n\t\t\t\t\t\texisting.id = normalizedId;\n\t\t\t\t\t\tif (params.title !== undefined) existing.title = params.title;\n\t\t\t\t\t\tif (params.status !== undefined) existing.status = params.status;\n\t\t\t\t\t\tif (params.tags !== undefined) existing.tags = params.tags;\n\t\t\t\t\t\tif (params.body !== undefined) existing.body = params.body;\n\t\t\t\t\t\tif (!existing.created_at) existing.created_at = new Date().toISOString();\n\t\t\t\t\t\tclearAssignmentIfClosed(existing);\n\n\t\t\t\t\t\tawait writeTodoFile(filePath, existing);\n\t\t\t\t\t\treturn existing;\n\t\t\t\t\t});\n\n\t\t\t\t\tif (typeof result === \"object\" && \"error\" in result) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: result.error }],\n\t\t\t\t\t\t\tdetails: { action: \"update\", error: result.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\tconst updatedTodo = result as TodoRecord;\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoForAgent(updatedTodo) }],\n\t\t\t\t\t\tdetails: { action: \"update\", todo: updatedTodo },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"append\": {\n\t\t\t\t\tif (!params.id) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: id required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"append\", error: \"id required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst validated = validateTodoId(params.id);\n\t\t\t\t\tif (\"error\" in validated) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: validated.error }],\n\t\t\t\t\t\t\tdetails: { action: \"append\", error: validated.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst normalizedId = validated.id;\n\t\t\t\t\tconst displayId = formatTodoId(normalizedId);\n\t\t\t\t\tconst filePath = getTodoPath(todosDir, normalizedId);\n\t\t\t\t\tif (!existsSync(filePath)) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: `Todo ${displayId} not found` }],\n\t\t\t\t\t\t\tdetails: { action: \"append\", error: \"not found\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst result = await withTodoLock(todosDir, normalizedId, ctx, async () => {\n\t\t\t\t\t\tconst existing = await ensureTodoExists(filePath, normalizedId);\n\t\t\t\t\t\tif (!existing) return { error: `Todo ${displayId} not found` } as const;\n\t\t\t\t\t\tif (!params.body || !params.body.trim()) {\n\t\t\t\t\t\t\treturn existing;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst updated = await appendTodoBody(filePath, existing, params.body);\n\t\t\t\t\t\treturn updated;\n\t\t\t\t\t});\n\n\t\t\t\t\tif (typeof result === \"object\" && \"error\" in result) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: result.error }],\n\t\t\t\t\t\t\tdetails: { action: \"append\", error: result.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\tconst updatedTodo = result as TodoRecord;\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoForAgent(updatedTodo) }],\n\t\t\t\t\t\tdetails: { action: \"append\", todo: updatedTodo },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"claim\": {\n\t\t\t\t\tif (!params.id) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: id required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"claim\", error: \"id required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst result = await claimTodoAssignment(\n\t\t\t\t\t\ttodosDir,\n\t\t\t\t\t\tparams.id,\n\t\t\t\t\t\tctx,\n\t\t\t\t\t\tBoolean(params.force),\n\t\t\t\t\t);\n\t\t\t\t\tif (typeof result === \"object\" && \"error\" in result) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: result.error }],\n\t\t\t\t\t\t\tdetails: { action: \"claim\", error: result.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst updatedTodo = result as TodoRecord;\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoForAgent(updatedTodo) }],\n\t\t\t\t\t\tdetails: { action: \"claim\", todo: updatedTodo },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"release\": {\n\t\t\t\t\tif (!params.id) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: id required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"release\", error: \"id required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst result = await releaseTodoAssignment(\n\t\t\t\t\t\ttodosDir,\n\t\t\t\t\t\tparams.id,\n\t\t\t\t\t\tctx,\n\t\t\t\t\t\tBoolean(params.force),\n\t\t\t\t\t);\n\t\t\t\t\tif (typeof result === \"object\" && \"error\" in result) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: result.error }],\n\t\t\t\t\t\t\tdetails: { action: \"release\", error: result.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst updatedTodo = result as TodoRecord;\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoForAgent(updatedTodo) }],\n\t\t\t\t\t\tdetails: { action: \"release\", todo: updatedTodo },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"delete\": {\n\t\t\t\t\tif (!params.id) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: id required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"delete\", error: \"id required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\tconst validated = validateTodoId(params.id);\n\t\t\t\t\tif (\"error\" in validated) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: validated.error }],\n\t\t\t\t\t\t\tdetails: { action: \"delete\", error: validated.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst result = await deleteTodo(todosDir, validated.id, ctx);\n\t\t\t\t\tif (typeof result === \"object\" && \"error\" in result) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: result.error }],\n\t\t\t\t\t\t\tdetails: { action: \"delete\", error: result.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\ttype: \"text\",\n\t\t\t\t\t\t\t\ttext: serializeTodoForAgent(result as TodoRecord),\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t],\n\t\t\t\t\t\tdetails: { action: \"delete\", todo: result as TodoRecord },\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\n\t\trenderCall(args, theme) {\n\t\t\tconst action = typeof args.action === \"string\" ? args.action : \"\";\n\t\t\tconst id = typeof args.id === \"string\" ? args.id : \"\";\n\t\t\tconst normalizedId = id ? normalizeTodoId(id) : \"\";\n\t\t\tconst title = typeof args.title === \"string\" ? args.title : \"\";\n\t\t\tlet text = theme.fg(\"toolTitle\", theme.bold(\"todo \")) + theme.fg(\"muted\", action);\n\t\t\tif (normalizedId) {\n\t\t\t\ttext += \" \" + theme.fg(\"accent\", formatTodoId(normalizedId));\n\t\t\t}\n\t\t\tif (title) {\n\t\t\t\ttext += \" \" + theme.fg(\"dim\", `\"${title}\"`);\n\t\t\t}\n\t\t\treturn new Text(text, 0, 0);\n\t\t},\n\n\t\trenderResult(result, { expanded, isPartial }, theme) {\n\t\t\tconst details = result.details as TodoToolDetails | undefined;\n\t\t\tif (isPartial) {\n\t\t\t\treturn new Text(theme.fg(\"warning\", \"Processing...\"), 0, 0);\n\t\t\t}\n\t\t\tif (!details) {\n\t\t\t\tconst text = result.content[0];\n\t\t\t\treturn new Text(text?.type === \"text\" ? text.text : \"\", 0, 0);\n\t\t\t}\n\n\t\t\tif (details.error) {\n\t\t\t\treturn new Text(theme.fg(\"error\", `Error: ${details.error}`), 0, 0);\n\t\t\t}\n\n\t\t\tif (details.action === \"list\" || details.action === \"list-all\") {\n\t\t\t\tlet text = renderTodoList(theme, details.todos, expanded, details.currentSessionId);\n\t\t\t\tif (!expanded) {\n\t\t\t\t\tconst { closedTodos } = splitTodosByAssignment(details.todos);\n\t\t\t\t\tif (closedTodos.length) {\n\t\t\t\t\t\ttext = appendExpandHint(theme, text);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn new Text(text, 0, 0);\n\t\t\t}\n\n\t\t\tif (!(\"todo\" in details) || !details.todo) {\n\t\t\t\tconst text = result.content[0];\n\t\t\t\treturn new Text(text?.type === \"text\" ? text.text : \"\", 0, 0);\n\t\t\t}\n\n\t\t\tlet text = renderTodoDetail(theme, details.todo, expanded);\n\t\t\tconst actionLabel =\n\t\t\t\tdetails.action === \"create\"\n\t\t\t\t\t? \"Created\"\n\t\t\t\t\t: details.action === \"update\"\n\t\t\t\t\t\t? \"Updated\"\n\t\t\t\t\t\t: details.action === \"append\"\n\t\t\t\t\t\t\t? \"Appended to\"\n\t\t\t\t\t\t\t: details.action === \"delete\"\n\t\t\t\t\t\t\t\t? \"Deleted\"\n\t\t\t\t\t\t\t\t: details.action === \"claim\"\n\t\t\t\t\t\t\t\t\t? \"Claimed\"\n\t\t\t\t\t\t\t\t\t: details.action === \"release\"\n\t\t\t\t\t\t\t\t\t\t? \"Released\"\n\t\t\t\t\t\t\t\t\t\t: null;\n\t\t\tif (actionLabel) {\n\t\t\t\tconst lines = text.split(\"\\n\");\n\t\t\t\tlines[0] = theme.fg(\"success\", \"✓ \") + theme.fg(\"muted\", `${actionLabel} `) + lines[0];\n\t\t\t\ttext = lines.join(\"\\n\");\n\t\t\t}\n\t\t\tif (!expanded) {\n\t\t\t\ttext = appendExpandHint(theme, text);\n\t\t\t}\n\t\t\treturn new Text(text, 0, 0);\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"todos.d.ts","sourceRoot":"","sources":["../../../src/core/tools/todos.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,OAAO,KAAK,EAAoB,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAU/E,UAAU,eAAe;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,UAAU,UAAW,SAAQ,eAAe;IAC3C,IAAI,EAAE,MAAM,CAAC;CACb;AASD,QAAA,MAAM,UAAU;;;;;;;;EAsBd,CAAC;AAaH,KAAK,eAAe,GACjB;IACA,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC;IAC5B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CACd,GACD;IACA,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IAChF,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAymBL,eAAO,MAAM,uBAAuB,EAAE,MAAM,EAE3C,CAAC;AAEF,wBAAgB,wBAAwB,CACvC,GAAG,GAAE,MAAsB,GACzB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,CAAC,CA6WpD","sourcesContent":["/**\n * This tool stores todo items as files under <todo-dir> (defaults to\n * <CONFIG_DIR_NAME>/todos, or the path in <APP_NAME>_TODO_PATH).  Each todo is\n * a standalone markdown file named <id>.md and an optional <id>.lock file is\n * used while a session is editing it.\n *\n * File format in <CONFIG_DIR_NAME>/todos:\n * - The file starts with a JSON object (not YAML) containing the front matter:\n *   { id, title, tags, status, created_at, assigned_to_session }\n * - After the JSON block comes optional markdown body text separated by a blank line.\n * - Example:\n *   {\n *     \"id\": \"deadbeef\",\n *     \"title\": \"Add tests\",\n *     \"tags\": [\"qa\"],\n *     \"status\": \"open\",\n *     \"created_at\": \"2026-01-25T17:00:00.000Z\",\n *     \"assigned_to_session\": \"session.json\"\n *   }\n *\n *   Notes about the work go here.\n */\nimport { StringEnum } from \"@earendil-works/pi-ai\";\nimport { Text } from \"@earendil-works/pi-tui\";\nimport crypto from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { Type } from \"typebox\";\nimport { APP_NAME, CONFIG_DIR_NAME, getEnvValue } from \"../../config.ts\";\nimport type { ExtensionContext, ToolDefinition } from \"../extensions/types.ts\";\nimport { keyHint } from \"../../modes/interactive/components/keybinding-hints.ts\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\n\nconst TODO_DIR_NAME = `${CONFIG_DIR_NAME}/todos`;\nconst TODO_PATH_ENV = `${APP_NAME.toUpperCase()}_TODO_PATH`;\nconst TODO_ID_PREFIX = \"TODO-\";\nconst TODO_ID_PATTERN = /^[a-f0-9]{8}$/i;\nconst LOCK_TTL_MS = 30 * 60 * 1000;\n\ninterface TodoFrontMatter {\n\tid: string;\n\ttitle: string;\n\ttags: string[];\n\tstatus: string;\n\tcreated_at: string;\n\tassigned_to_session?: string;\n}\n\ninterface TodoRecord extends TodoFrontMatter {\n\tbody: string;\n}\n\ninterface LockInfo {\n\tid: string;\n\tpid: number;\n\tsession?: string | null;\n\tcreated_at: string;\n}\n\nconst TodoParams = Type.Object({\n\taction: StringEnum([\n\t\t\"list\",\n\t\t\"list-all\",\n\t\t\"get\",\n\t\t\"create\",\n\t\t\"update\",\n\t\t\"append\",\n\t\t\"delete\",\n\t\t\"claim\",\n\t\t\"release\",\n\t] as const),\n\tid: Type.Optional(Type.String({ description: \"Todo id (TODO-<hex> or raw hex filename)\" })),\n\ttitle: Type.Optional(Type.String({ description: \"Short summary shown in lists\" })),\n\tstatus: Type.Optional(Type.String({ description: \"Todo status\" })),\n\ttags: Type.Optional(Type.Array(Type.String({ description: \"Todo tag\" }))),\n\tbody: Type.Optional(\n\t\tType.String({\n\t\t\tdescription: \"Long-form details (markdown). Update replaces; append adds.\",\n\t\t}),\n\t),\n\tforce: Type.Optional(Type.Boolean({ description: \"Override another session's assignment\" })),\n});\n\ntype TodoAction =\n\t| \"list\"\n\t| \"list-all\"\n\t| \"get\"\n\t| \"create\"\n\t| \"update\"\n\t| \"append\"\n\t| \"delete\"\n\t| \"claim\"\n\t| \"release\";\n\ntype TodoToolDetails =\n\t| {\n\t\t\taction: \"list\" | \"list-all\";\n\t\t\ttodos: TodoFrontMatter[];\n\t\t\tcurrentSessionId?: string;\n\t\t\terror?: string;\n\t  }\n\t| {\n\t\t\taction: \"get\" | \"create\" | \"update\" | \"append\" | \"delete\" | \"claim\" | \"release\";\n\t\t\ttodo?: TodoRecord;\n\t\t\terror?: string;\n\t  };\n\nfunction formatTodoId(id: string): string {\n\treturn `${TODO_ID_PREFIX}${id}`;\n}\n\nfunction normalizeTodoId(id: string): string {\n\tlet trimmed = id.trim();\n\tif (trimmed.startsWith(\"#\")) {\n\t\ttrimmed = trimmed.slice(1);\n\t}\n\tif (trimmed.toUpperCase().startsWith(TODO_ID_PREFIX)) {\n\t\ttrimmed = trimmed.slice(TODO_ID_PREFIX.length);\n\t}\n\treturn trimmed;\n}\n\nfunction validateTodoId(id: string): { id: string } | { error: string } {\n\tconst normalized = normalizeTodoId(id);\n\tif (!normalized || !TODO_ID_PATTERN.test(normalized)) {\n\t\treturn { error: \"Invalid todo id. Expected TODO-<hex>.\" };\n\t}\n\treturn { id: normalized.toLowerCase() };\n}\n\nfunction displayTodoId(id: string): string {\n\treturn formatTodoId(normalizeTodoId(id));\n}\n\nfunction isTodoClosed(status: string): boolean {\n\treturn [\"closed\", \"done\"].includes(status.toLowerCase());\n}\n\nfunction clearAssignmentIfClosed(todo: TodoFrontMatter): void {\n\tif (isTodoClosed(getTodoStatus(todo))) {\n\t\ttodo.assigned_to_session = undefined;\n\t}\n}\n\nfunction sortTodos(todos: TodoFrontMatter[]): TodoFrontMatter[] {\n\treturn [...todos].sort((a, b) => {\n\t\tconst aClosed = isTodoClosed(a.status);\n\t\tconst bClosed = isTodoClosed(b.status);\n\t\tif (aClosed !== bClosed) return aClosed ? 1 : -1;\n\t\tconst aAssigned = !aClosed && Boolean(a.assigned_to_session);\n\t\tconst bAssigned = !bClosed && Boolean(b.assigned_to_session);\n\t\tif (aAssigned !== bAssigned) return aAssigned ? -1 : 1;\n\t\treturn (a.created_at || \"\").localeCompare(b.created_at || \"\");\n\t});\n}\n\nfunction getTodosDir(cwd: string): string {\n\tconst overridePath = getEnvValue(TODO_PATH_ENV);\n\tif (overridePath && overridePath.trim()) {\n\t\treturn path.resolve(cwd, overridePath.trim());\n\t}\n\treturn path.resolve(cwd, TODO_DIR_NAME);\n}\n\nfunction getTodosDirLabel(cwd: string): string {\n\tconst overridePath = getEnvValue(TODO_PATH_ENV);\n\tif (overridePath && overridePath.trim()) {\n\t\treturn path.resolve(cwd, overridePath.trim());\n\t}\n\treturn TODO_DIR_NAME;\n}\n\nfunction getTodoPath(todosDir: string, id: string): string {\n\treturn path.join(todosDir, `${id}.md`);\n}\n\nfunction getLockPath(todosDir: string, id: string): string {\n\treturn path.join(todosDir, `${id}.lock`);\n}\n\nfunction parseFrontMatter(text: string, idFallback: string): TodoFrontMatter {\n\tconst data: TodoFrontMatter = {\n\t\tid: idFallback,\n\t\ttitle: \"\",\n\t\ttags: [],\n\t\tstatus: \"open\",\n\t\tcreated_at: \"\",\n\t\tassigned_to_session: undefined,\n\t};\n\n\tconst trimmed = text.trim();\n\tif (!trimmed) return data;\n\n\ttry {\n\t\tconst parsed = JSON.parse(trimmed) as Partial<TodoFrontMatter> | null;\n\t\tif (!parsed || typeof parsed !== \"object\") return data;\n\t\tif (typeof parsed.id === \"string\" && parsed.id) data.id = parsed.id;\n\t\tif (typeof parsed.title === \"string\") data.title = parsed.title;\n\t\tif (typeof parsed.status === \"string\" && parsed.status) data.status = parsed.status;\n\t\tif (typeof parsed.created_at === \"string\") data.created_at = parsed.created_at;\n\t\tif (\n\t\t\ttypeof parsed.assigned_to_session === \"string\" &&\n\t\t\tparsed.assigned_to_session.trim()\n\t\t) {\n\t\t\tdata.assigned_to_session = parsed.assigned_to_session;\n\t\t}\n\t\tif (Array.isArray(parsed.tags)) {\n\t\t\tdata.tags = parsed.tags.filter((tag): tag is string => typeof tag === \"string\");\n\t\t}\n\t} catch {\n\t\treturn data;\n\t}\n\n\treturn data;\n}\n\nfunction findJsonObjectEnd(content: string): number {\n\tlet depth = 0;\n\tlet inString = false;\n\tlet escaped = false;\n\n\tfor (let i = 0; i < content.length; i += 1) {\n\t\tconst char = content[i];\n\n\t\tif (inString) {\n\t\t\tif (escaped) {\n\t\t\t\tescaped = false;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (char === \"\\\\\") {\n\t\t\t\tescaped = true;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (char === '\"') {\n\t\t\t\tinString = false;\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (char === '\"') {\n\t\t\tinString = true;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (char === \"{\") {\n\t\t\tdepth += 1;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (char === \"}\") {\n\t\t\tdepth -= 1;\n\t\t\tif (depth === 0) return i;\n\t\t}\n\t}\n\n\treturn -1;\n}\n\nfunction splitFrontMatter(content: string): { frontMatter: string; body: string } {\n\tif (!content.startsWith(\"{\")) {\n\t\treturn { frontMatter: \"\", body: content };\n\t}\n\n\tconst endIndex = findJsonObjectEnd(content);\n\tif (endIndex === -1) {\n\t\treturn { frontMatter: \"\", body: content };\n\t}\n\n\tconst frontMatter = content.slice(0, endIndex + 1);\n\tconst body = content.slice(endIndex + 1).replace(/^\\r?\\n+/, \"\");\n\treturn { frontMatter, body };\n}\n\nfunction parseTodoContent(content: string, idFallback: string): TodoRecord {\n\tconst { frontMatter, body } = splitFrontMatter(content);\n\tconst parsed = parseFrontMatter(frontMatter, idFallback);\n\treturn {\n\t\tid: idFallback,\n\t\ttitle: parsed.title,\n\t\ttags: parsed.tags ?? [],\n\t\tstatus: parsed.status,\n\t\tcreated_at: parsed.created_at,\n\t\tassigned_to_session: parsed.assigned_to_session,\n\t\tbody: body ?? \"\",\n\t};\n}\n\nfunction serializeTodo(todo: TodoRecord): string {\n\tconst frontMatter = JSON.stringify(\n\t\t{\n\t\t\tid: todo.id,\n\t\t\ttitle: todo.title,\n\t\t\ttags: todo.tags ?? [],\n\t\t\tstatus: todo.status,\n\t\t\tcreated_at: todo.created_at,\n\t\t\tassigned_to_session: todo.assigned_to_session || undefined,\n\t\t},\n\t\tnull,\n\t\t2,\n\t);\n\n\tconst body = todo.body ?? \"\";\n\tconst trimmedBody = body.replace(/^\\n+/, \"\").replace(/\\s+$/, \"\");\n\tif (!trimmedBody) return `${frontMatter}\\n`;\n\treturn `${frontMatter}\\n\\n${trimmedBody}\\n`;\n}\n\nasync function ensureTodosDir(todosDir: string) {\n\tawait fs.mkdir(todosDir, { recursive: true });\n}\n\nasync function readTodoFile(filePath: string, idFallback: string): Promise<TodoRecord> {\n\tconst content = await fs.readFile(filePath, \"utf8\");\n\treturn parseTodoContent(content, idFallback);\n}\n\nasync function writeTodoFile(filePath: string, todo: TodoRecord) {\n\tawait fs.writeFile(filePath, serializeTodo(todo), \"utf8\");\n}\n\nasync function generateTodoId(todosDir: string): Promise<string> {\n\tfor (let attempt = 0; attempt < 10; attempt += 1) {\n\t\tconst id = crypto.randomBytes(4).toString(\"hex\");\n\t\tconst todoPath = getTodoPath(todosDir, id);\n\t\tif (!existsSync(todoPath)) return id;\n\t}\n\tthrow new Error(\"Failed to generate unique todo id\");\n}\n\nasync function readLockInfo(lockPath: string): Promise<LockInfo | null> {\n\ttry {\n\t\tconst raw = await fs.readFile(lockPath, \"utf8\");\n\t\treturn JSON.parse(raw) as LockInfo;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nasync function acquireLock(\n\ttodosDir: string,\n\tid: string,\n\tctx: ExtensionContext,\n): Promise<(() => Promise<void>) | { error: string }> {\n\tconst lockPath = getLockPath(todosDir, id);\n\tconst now = Date.now();\n\tconst session = ctx.sessionManager.getSessionFile();\n\n\tfor (let attempt = 0; attempt < 2; attempt += 1) {\n\t\ttry {\n\t\t\tconst handle = await fs.open(lockPath, \"wx\");\n\t\t\tconst info: LockInfo = {\n\t\t\t\tid,\n\t\t\t\tpid: process.pid,\n\t\t\t\tsession,\n\t\t\t\tcreated_at: new Date(now).toISOString(),\n\t\t\t};\n\t\t\tawait handle.writeFile(JSON.stringify(info, null, 2), \"utf8\");\n\t\t\tawait handle.close();\n\t\t\treturn async () => {\n\t\t\t\ttry {\n\t\t\t\t\tawait fs.unlink(lockPath);\n\t\t\t\t} catch {\n\t\t\t\t\t// ignore\n\t\t\t\t}\n\t\t\t};\n\t\t} catch (error) {\n\t\t\tconst fsError = error as { code?: string; message?: string };\n\t\t\tif (fsError.code !== \"EEXIST\") {\n\t\t\t\treturn {\n\t\t\t\t\terror: `Failed to acquire lock: ${fsError.message ?? \"unknown error\"}`,\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst stats = await fs.stat(lockPath).catch(() => null);\n\t\t\tconst lockAge = stats ? now - stats.mtimeMs : LOCK_TTL_MS + 1;\n\t\t\tif (lockAge <= LOCK_TTL_MS) {\n\t\t\t\tconst info = await readLockInfo(lockPath);\n\t\t\t\tconst owner = info?.session ? ` (session ${info.session})` : \"\";\n\t\t\t\treturn {\n\t\t\t\t\terror: `Todo ${displayTodoId(id)} is locked${owner}. Try again later.`,\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (!ctx.hasUI) {\n\t\t\t\treturn {\n\t\t\t\t\terror: `Todo ${displayTodoId(id)} lock is stale; rerun in interactive mode to steal it.`,\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst ok = await ctx.ui.confirm(\n\t\t\t\t\"Todo locked\",\n\t\t\t\t`Todo ${displayTodoId(id)} appears locked. Steal the lock?`,\n\t\t\t);\n\t\t\tif (!ok) {\n\t\t\t\treturn { error: `Todo ${displayTodoId(id)} remains locked.` };\n\t\t\t}\n\t\t\tawait fs.unlink(lockPath).catch(() => undefined);\n\t\t}\n\t}\n\n\treturn { error: `Failed to acquire lock for todo ${displayTodoId(id)}.` };\n}\n\nasync function withTodoLock<T>(\n\ttodosDir: string,\n\tid: string,\n\tctx: ExtensionContext,\n\tfn: () => Promise<T>,\n): Promise<T | { error: string }> {\n\tconst lock = await acquireLock(todosDir, id, ctx);\n\tif (typeof lock === \"object\" && \"error\" in lock) return lock;\n\ttry {\n\t\treturn await fn();\n\t} finally {\n\t\tawait lock();\n\t}\n}\n\nasync function listTodos(todosDir: string): Promise<TodoFrontMatter[]> {\n\tlet entries: string[] = [];\n\ttry {\n\t\tentries = await fs.readdir(todosDir);\n\t} catch {\n\t\treturn [];\n\t}\n\n\tconst todos: TodoFrontMatter[] = [];\n\tfor (const entry of entries) {\n\t\tif (!entry.endsWith(\".md\")) continue;\n\t\tconst id = entry.slice(0, -3);\n\t\tconst filePath = path.join(todosDir, entry);\n\t\ttry {\n\t\t\tconst content = await fs.readFile(filePath, \"utf8\");\n\t\t\tconst { frontMatter } = splitFrontMatter(content);\n\t\t\tconst parsed = parseFrontMatter(frontMatter, id);\n\t\t\ttodos.push({\n\t\t\t\tid,\n\t\t\t\ttitle: parsed.title,\n\t\t\t\ttags: parsed.tags ?? [],\n\t\t\t\tstatus: parsed.status,\n\t\t\t\tcreated_at: parsed.created_at,\n\t\t\t\tassigned_to_session: parsed.assigned_to_session,\n\t\t\t});\n\t\t} catch {\n\t\t\t// ignore unreadable todo\n\t\t}\n\t}\n\n\treturn sortTodos(todos);\n}\n\nfunction getTodoTitle(todo: TodoFrontMatter): string {\n\treturn todo.title || \"(untitled)\";\n}\n\nfunction getTodoStatus(todo: TodoFrontMatter): string {\n\treturn todo.status || \"open\";\n}\n\nfunction renderAssignmentSuffix(\n\ttheme: Theme,\n\ttodo: TodoFrontMatter,\n\tcurrentSessionId?: string,\n): string {\n\tif (!todo.assigned_to_session) return \"\";\n\tconst isCurrent = todo.assigned_to_session === currentSessionId;\n\tconst color = isCurrent ? \"success\" : \"dim\";\n\tconst suffix = isCurrent ? \", current\" : \"\";\n\treturn theme.fg(color, ` (assigned: ${todo.assigned_to_session}${suffix})`);\n}\n\nfunction splitTodosByAssignment(todos: TodoFrontMatter[]): {\n\tassignedTodos: TodoFrontMatter[];\n\topenTodos: TodoFrontMatter[];\n\tclosedTodos: TodoFrontMatter[];\n} {\n\tconst assignedTodos: TodoFrontMatter[] = [];\n\tconst openTodos: TodoFrontMatter[] = [];\n\tconst closedTodos: TodoFrontMatter[] = [];\n\tfor (const todo of todos) {\n\t\tif (isTodoClosed(getTodoStatus(todo))) {\n\t\t\tclosedTodos.push(todo);\n\t\t\tcontinue;\n\t\t}\n\t\tif (todo.assigned_to_session) {\n\t\t\tassignedTodos.push(todo);\n\t\t} else {\n\t\t\topenTodos.push(todo);\n\t\t}\n\t}\n\treturn { assignedTodos, openTodos, closedTodos };\n}\n\nfunction serializeTodoForAgent(todo: TodoRecord): string {\n\tconst payload = { ...todo, id: formatTodoId(todo.id) };\n\treturn JSON.stringify(payload, null, 2);\n}\n\nfunction serializeTodoListForAgent(todos: TodoFrontMatter[]): string {\n\tconst { assignedTodos, openTodos, closedTodos } = splitTodosByAssignment(todos);\n\tconst mapTodo = (todo: TodoFrontMatter) => ({\n\t\t...todo,\n\t\tid: formatTodoId(todo.id),\n\t});\n\treturn JSON.stringify(\n\t\t{\n\t\t\tassigned: assignedTodos.map(mapTodo),\n\t\t\topen: openTodos.map(mapTodo),\n\t\t\tclosed: closedTodos.map(mapTodo),\n\t\t},\n\t\tnull,\n\t\t2,\n\t);\n}\n\nfunction renderTodoHeading(\n\ttheme: Theme,\n\ttodo: TodoFrontMatter,\n\tcurrentSessionId?: string,\n): string {\n\tconst closed = isTodoClosed(getTodoStatus(todo));\n\tconst titleColor = closed ? \"dim\" : \"text\";\n\tconst tagText = todo.tags.length ? theme.fg(\"dim\", ` [${todo.tags.join(\", \")}]`) : \"\";\n\tconst assignmentText = renderAssignmentSuffix(theme, todo, currentSessionId);\n\treturn (\n\t\ttheme.fg(\"accent\", formatTodoId(todo.id)) +\n\t\t\" \" +\n\t\ttheme.fg(titleColor, getTodoTitle(todo)) +\n\t\ttagText +\n\t\tassignmentText\n\t);\n}\n\nfunction renderTodoList(\n\ttheme: Theme,\n\ttodos: TodoFrontMatter[],\n\texpanded: boolean,\n\tcurrentSessionId?: string,\n): string {\n\tif (!todos.length) return theme.fg(\"dim\", \"No todos\");\n\n\tconst { assignedTodos, openTodos, closedTodos } = splitTodosByAssignment(todos);\n\tconst lines: string[] = [];\n\tconst pushSection = (label: string, sectionTodos: TodoFrontMatter[]) => {\n\t\tlines.push(theme.fg(\"muted\", `${label} (${sectionTodos.length})`));\n\t\tif (!sectionTodos.length) {\n\t\t\tlines.push(theme.fg(\"dim\", \"  none\"));\n\t\t\treturn;\n\t\t}\n\t\tconst maxItems = expanded ? sectionTodos.length : Math.min(sectionTodos.length, 3);\n\t\tfor (let i = 0; i < maxItems; i++) {\n\t\t\tlines.push(`  ${renderTodoHeading(theme, sectionTodos[i], currentSessionId)}`);\n\t\t}\n\t\tif (!expanded && sectionTodos.length > maxItems) {\n\t\t\tlines.push(theme.fg(\"dim\", `  ... ${sectionTodos.length - maxItems} more`));\n\t\t}\n\t};\n\n\tconst sections: Array<{ label: string; todos: TodoFrontMatter[] }> = [\n\t\t{ label: \"Assigned todos\", todos: assignedTodos },\n\t\t{ label: \"Open todos\", todos: openTodos },\n\t\t{ label: \"Closed todos\", todos: closedTodos },\n\t];\n\n\tsections.forEach((section, index) => {\n\t\tif (index > 0) lines.push(\"\");\n\t\tpushSection(section.label, section.todos);\n\t});\n\n\treturn lines.join(\"\\n\");\n}\n\nfunction renderTodoDetail(theme: Theme, todo: TodoRecord, expanded: boolean): string {\n\tconst summary = renderTodoHeading(theme, todo);\n\tif (!expanded) return summary;\n\n\tconst tags = todo.tags.length ? todo.tags.join(\", \") : \"none\";\n\tconst createdAt = todo.created_at || \"unknown\";\n\tconst bodyText = todo.body?.trim() ? todo.body.trim() : \"No details yet.\";\n\tconst bodyLines = bodyText.split(\"\\n\");\n\n\tconst lines = [\n\t\tsummary,\n\t\ttheme.fg(\"muted\", `Status: ${getTodoStatus(todo)}`),\n\t\ttheme.fg(\"muted\", `Tags: ${tags}`),\n\t\ttheme.fg(\"muted\", `Created: ${createdAt}`),\n\t\t\"\",\n\t\ttheme.fg(\"muted\", \"Body:\"),\n\t\t...bodyLines.map((line) => theme.fg(\"text\", `  ${line}`)),\n\t];\n\n\treturn lines.join(\"\\n\");\n}\n\nfunction appendExpandHint(theme: Theme, text: string): string {\n\treturn `${text}\\n${theme.fg(\"dim\", `(${keyHint(\"app.tools.expand\", \"Expand\")})`)}`;\n}\n\nasync function ensureTodoExists(filePath: string, id: string): Promise<TodoRecord | null> {\n\tif (!existsSync(filePath)) return null;\n\treturn readTodoFile(filePath, id);\n}\n\nasync function appendTodoBody(\n\tfilePath: string,\n\ttodo: TodoRecord,\n\ttext: string,\n): Promise<TodoRecord> {\n\tconst spacer = todo.body.trim().length ? \"\\n\\n\" : \"\";\n\ttodo.body = `${todo.body.replace(/\\s+$/, \"\")}${spacer}${text.trim()}\\n`;\n\tawait writeTodoFile(filePath, todo);\n\treturn todo;\n}\n\nasync function claimTodoAssignment(\n\ttodosDir: string,\n\tid: string,\n\tctx: ExtensionContext,\n\tforce = false,\n): Promise<TodoRecord | { error: string }> {\n\tconst validated = validateTodoId(id);\n\tif (\"error\" in validated) {\n\t\treturn { error: validated.error };\n\t}\n\tconst normalizedId = validated.id;\n\tconst filePath = getTodoPath(todosDir, normalizedId);\n\tif (!existsSync(filePath)) {\n\t\treturn { error: `Todo ${displayTodoId(id)} not found` };\n\t}\n\tconst sessionId = ctx.sessionManager.getSessionId();\n\tconst result = await withTodoLock(todosDir, normalizedId, ctx, async () => {\n\t\tconst existing = await ensureTodoExists(filePath, normalizedId);\n\t\tif (!existing) return { error: `Todo ${displayTodoId(id)} not found` } as const;\n\t\tif (isTodoClosed(existing.status)) {\n\t\t\treturn { error: `Todo ${displayTodoId(id)} is closed` } as const;\n\t\t}\n\t\tconst assigned = existing.assigned_to_session;\n\t\tif (assigned && assigned !== sessionId && !force) {\n\t\t\treturn {\n\t\t\t\terror: `Todo ${displayTodoId(id)} is already assigned to session ${assigned}. Use force to override.`,\n\t\t\t} as const;\n\t\t}\n\t\tif (assigned !== sessionId) {\n\t\t\texisting.assigned_to_session = sessionId;\n\t\t\tawait writeTodoFile(filePath, existing);\n\t\t}\n\t\treturn existing;\n\t});\n\n\tif (typeof result === \"object\" && \"error\" in result) {\n\t\treturn { error: result.error };\n\t}\n\n\treturn result;\n}\n\nasync function releaseTodoAssignment(\n\ttodosDir: string,\n\tid: string,\n\tctx: ExtensionContext,\n\tforce = false,\n): Promise<TodoRecord | { error: string }> {\n\tconst validated = validateTodoId(id);\n\tif (\"error\" in validated) {\n\t\treturn { error: validated.error };\n\t}\n\tconst normalizedId = validated.id;\n\tconst filePath = getTodoPath(todosDir, normalizedId);\n\tif (!existsSync(filePath)) {\n\t\treturn { error: `Todo ${displayTodoId(id)} not found` };\n\t}\n\tconst sessionId = ctx.sessionManager.getSessionId();\n\tconst result = await withTodoLock(todosDir, normalizedId, ctx, async () => {\n\t\tconst existing = await ensureTodoExists(filePath, normalizedId);\n\t\tif (!existing) return { error: `Todo ${displayTodoId(id)} not found` } as const;\n\t\tconst assigned = existing.assigned_to_session;\n\t\tif (!assigned) {\n\t\t\treturn existing;\n\t\t}\n\t\tif (assigned !== sessionId && !force) {\n\t\t\treturn {\n\t\t\t\terror: `Todo ${displayTodoId(id)} is assigned to session ${assigned}. Use force to release.`,\n\t\t\t} as const;\n\t\t}\n\t\texisting.assigned_to_session = undefined;\n\t\tawait writeTodoFile(filePath, existing);\n\t\treturn existing;\n\t});\n\n\tif (typeof result === \"object\" && \"error\" in result) {\n\t\treturn { error: result.error };\n\t}\n\n\treturn result;\n}\n\nasync function deleteTodo(\n\ttodosDir: string,\n\tid: string,\n\tctx: ExtensionContext,\n): Promise<TodoRecord | { error: string }> {\n\tconst validated = validateTodoId(id);\n\tif (\"error\" in validated) {\n\t\treturn { error: validated.error };\n\t}\n\tconst normalizedId = validated.id;\n\tconst filePath = getTodoPath(todosDir, normalizedId);\n\tif (!existsSync(filePath)) {\n\t\treturn { error: `Todo ${displayTodoId(id)} not found` };\n\t}\n\n\tconst result = await withTodoLock(todosDir, normalizedId, ctx, async () => {\n\t\tconst existing = await ensureTodoExists(filePath, normalizedId);\n\t\tif (!existing) return { error: `Todo ${displayTodoId(id)} not found` } as const;\n\t\tawait fs.unlink(filePath);\n\t\treturn existing;\n\t});\n\n\tif (typeof result === \"object\" && \"error\" in result) {\n\t\treturn { error: result.error };\n\t}\n\n\treturn result;\n}\n\nexport const DEFAULT_PROMPT_GUIDANCE: string[] = [\n\t\"**To-do management**: If the user has a complex task that can be broken down into actionable steps, use the `todo` tool to create a task list before proceeding. This ensures clarity and alignment with the user's goals and that you have a way to track your work and ensure you are meeting the user's expectations.\",\n];\n\nexport function createTodoToolDefinition(\n\tcwd: string = process.cwd(),\n): ToolDefinition<typeof TodoParams, TodoToolDetails> {\n\tconst todosDirLabel = getTodosDirLabel(cwd);\n\n\treturn {\n\t\tname: \"todo\",\n\t\tlabel: \"Todo\",\n\t\tdescription:\n\t\t\t`Manage file-based todos in ${todosDirLabel} (list, list-all, get, create, update, append, delete, claim, release). ` +\n\t\t\t\"Title is the short summary; body is long-form markdown notes (update replaces, append adds). \" +\n\t\t\t\"Todo ids are shown as TODO-<hex>; id parameters accept TODO-<hex> or the raw hex filename. \" +\n\t\t\t\"Claim tasks before working on them to avoid conflicts, and close them when complete.\",\n\t\tparameters: TodoParams,\n\t\tpromptGuidelines: DEFAULT_PROMPT_GUIDANCE,\n\n\t\tasync execute(_toolCallId, params, _signal, _onUpdate, ctx) {\n\t\t\tconst todosDir = getTodosDir(ctx.cwd);\n\t\t\tconst action: TodoAction = params.action;\n\n\t\t\tswitch (action) {\n\t\t\t\tcase \"list\": {\n\t\t\t\t\tconst todos = await listTodos(todosDir);\n\t\t\t\t\tconst { assignedTodos, openTodos } = splitTodosByAssignment(todos);\n\t\t\t\t\tconst listedTodos = [...assignedTodos, ...openTodos];\n\t\t\t\t\tconst currentSessionId = ctx.sessionManager.getSessionId();\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoListForAgent(listedTodos) }],\n\t\t\t\t\t\tdetails: { action: \"list\", todos: listedTodos, currentSessionId },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"list-all\": {\n\t\t\t\t\tconst todos = await listTodos(todosDir);\n\t\t\t\t\tconst currentSessionId = ctx.sessionManager.getSessionId();\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoListForAgent(todos) }],\n\t\t\t\t\t\tdetails: { action: \"list-all\", todos, currentSessionId },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"get\": {\n\t\t\t\t\tif (!params.id) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: id required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"get\", error: \"id required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst validated = validateTodoId(params.id);\n\t\t\t\t\tif (\"error\" in validated) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: validated.error }],\n\t\t\t\t\t\t\tdetails: { action: \"get\", error: validated.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst normalizedId = validated.id;\n\t\t\t\t\tconst displayId = formatTodoId(normalizedId);\n\t\t\t\t\tconst filePath = getTodoPath(todosDir, normalizedId);\n\t\t\t\t\tconst todo = await ensureTodoExists(filePath, normalizedId);\n\t\t\t\t\tif (!todo) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: `Todo ${displayId} not found` }],\n\t\t\t\t\t\t\tdetails: { action: \"get\", error: \"not found\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoForAgent(todo) }],\n\t\t\t\t\t\tdetails: { action: \"get\", todo },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"create\": {\n\t\t\t\t\tif (!params.title) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: title required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"create\", error: \"title required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tawait ensureTodosDir(todosDir);\n\t\t\t\t\tconst id = await generateTodoId(todosDir);\n\t\t\t\t\tconst filePath = getTodoPath(todosDir, id);\n\t\t\t\t\tconst todo: TodoRecord = {\n\t\t\t\t\t\tid,\n\t\t\t\t\t\ttitle: params.title,\n\t\t\t\t\t\ttags: params.tags ?? [],\n\t\t\t\t\t\tstatus: params.status ?? \"open\",\n\t\t\t\t\t\tcreated_at: new Date().toISOString(),\n\t\t\t\t\t\tbody: params.body ?? \"\",\n\t\t\t\t\t};\n\n\t\t\t\t\tconst result = await withTodoLock(todosDir, id, ctx, async () => {\n\t\t\t\t\t\tawait writeTodoFile(filePath, todo);\n\t\t\t\t\t\treturn todo;\n\t\t\t\t\t});\n\n\t\t\t\t\tif (typeof result === \"object\" && \"error\" in result) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: result.error }],\n\t\t\t\t\t\t\tdetails: { action: \"create\", error: result.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoForAgent(todo) }],\n\t\t\t\t\t\tdetails: { action: \"create\", todo },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"update\": {\n\t\t\t\t\tif (!params.id) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: id required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"update\", error: \"id required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst validated = validateTodoId(params.id);\n\t\t\t\t\tif (\"error\" in validated) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: validated.error }],\n\t\t\t\t\t\t\tdetails: { action: \"update\", error: validated.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst normalizedId = validated.id;\n\t\t\t\t\tconst displayId = formatTodoId(normalizedId);\n\t\t\t\t\tconst filePath = getTodoPath(todosDir, normalizedId);\n\t\t\t\t\tif (!existsSync(filePath)) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: `Todo ${displayId} not found` }],\n\t\t\t\t\t\t\tdetails: { action: \"update\", error: \"not found\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst result = await withTodoLock(todosDir, normalizedId, ctx, async () => {\n\t\t\t\t\t\tconst existing = await ensureTodoExists(filePath, normalizedId);\n\t\t\t\t\t\tif (!existing) return { error: `Todo ${displayId} not found` } as const;\n\n\t\t\t\t\t\texisting.id = normalizedId;\n\t\t\t\t\t\tif (params.title !== undefined) existing.title = params.title;\n\t\t\t\t\t\tif (params.status !== undefined) existing.status = params.status;\n\t\t\t\t\t\tif (params.tags !== undefined) existing.tags = params.tags;\n\t\t\t\t\t\tif (params.body !== undefined) existing.body = params.body;\n\t\t\t\t\t\tif (!existing.created_at) existing.created_at = new Date().toISOString();\n\t\t\t\t\t\tclearAssignmentIfClosed(existing);\n\n\t\t\t\t\t\tawait writeTodoFile(filePath, existing);\n\t\t\t\t\t\treturn existing;\n\t\t\t\t\t});\n\n\t\t\t\t\tif (typeof result === \"object\" && \"error\" in result) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: result.error }],\n\t\t\t\t\t\t\tdetails: { action: \"update\", error: result.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\tconst updatedTodo = result as TodoRecord;\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoForAgent(updatedTodo) }],\n\t\t\t\t\t\tdetails: { action: \"update\", todo: updatedTodo },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"append\": {\n\t\t\t\t\tif (!params.id) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: id required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"append\", error: \"id required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst validated = validateTodoId(params.id);\n\t\t\t\t\tif (\"error\" in validated) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: validated.error }],\n\t\t\t\t\t\t\tdetails: { action: \"append\", error: validated.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst normalizedId = validated.id;\n\t\t\t\t\tconst displayId = formatTodoId(normalizedId);\n\t\t\t\t\tconst filePath = getTodoPath(todosDir, normalizedId);\n\t\t\t\t\tif (!existsSync(filePath)) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: `Todo ${displayId} not found` }],\n\t\t\t\t\t\t\tdetails: { action: \"append\", error: \"not found\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst result = await withTodoLock(todosDir, normalizedId, ctx, async () => {\n\t\t\t\t\t\tconst existing = await ensureTodoExists(filePath, normalizedId);\n\t\t\t\t\t\tif (!existing) return { error: `Todo ${displayId} not found` } as const;\n\t\t\t\t\t\tif (!params.body || !params.body.trim()) {\n\t\t\t\t\t\t\treturn existing;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst updated = await appendTodoBody(filePath, existing, params.body);\n\t\t\t\t\t\treturn updated;\n\t\t\t\t\t});\n\n\t\t\t\t\tif (typeof result === \"object\" && \"error\" in result) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: result.error }],\n\t\t\t\t\t\t\tdetails: { action: \"append\", error: result.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\tconst updatedTodo = result as TodoRecord;\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoForAgent(updatedTodo) }],\n\t\t\t\t\t\tdetails: { action: \"append\", todo: updatedTodo },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"claim\": {\n\t\t\t\t\tif (!params.id) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: id required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"claim\", error: \"id required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst result = await claimTodoAssignment(\n\t\t\t\t\t\ttodosDir,\n\t\t\t\t\t\tparams.id,\n\t\t\t\t\t\tctx,\n\t\t\t\t\t\tBoolean(params.force),\n\t\t\t\t\t);\n\t\t\t\t\tif (typeof result === \"object\" && \"error\" in result) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: result.error }],\n\t\t\t\t\t\t\tdetails: { action: \"claim\", error: result.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst updatedTodo = result as TodoRecord;\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoForAgent(updatedTodo) }],\n\t\t\t\t\t\tdetails: { action: \"claim\", todo: updatedTodo },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"release\": {\n\t\t\t\t\tif (!params.id) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: id required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"release\", error: \"id required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst result = await releaseTodoAssignment(\n\t\t\t\t\t\ttodosDir,\n\t\t\t\t\t\tparams.id,\n\t\t\t\t\t\tctx,\n\t\t\t\t\t\tBoolean(params.force),\n\t\t\t\t\t);\n\t\t\t\t\tif (typeof result === \"object\" && \"error\" in result) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: result.error }],\n\t\t\t\t\t\t\tdetails: { action: \"release\", error: result.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst updatedTodo = result as TodoRecord;\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: serializeTodoForAgent(updatedTodo) }],\n\t\t\t\t\t\tdetails: { action: \"release\", todo: updatedTodo },\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tcase \"delete\": {\n\t\t\t\t\tif (!params.id) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: \"Error: id required\" }],\n\t\t\t\t\t\t\tdetails: { action: \"delete\", error: \"id required\" },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\tconst validated = validateTodoId(params.id);\n\t\t\t\t\tif (\"error\" in validated) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: validated.error }],\n\t\t\t\t\t\t\tdetails: { action: \"delete\", error: validated.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst result = await deleteTodo(todosDir, validated.id, ctx);\n\t\t\t\t\tif (typeof result === \"object\" && \"error\" in result) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: result.error }],\n\t\t\t\t\t\t\tdetails: { action: \"delete\", error: result.error },\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\ttype: \"text\",\n\t\t\t\t\t\t\t\ttext: serializeTodoForAgent(result as TodoRecord),\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t],\n\t\t\t\t\t\tdetails: { action: \"delete\", todo: result as TodoRecord },\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\n\t\trenderCall(args, theme) {\n\t\t\tconst action = typeof args.action === \"string\" ? args.action : \"\";\n\t\t\tconst id = typeof args.id === \"string\" ? args.id : \"\";\n\t\t\tconst normalizedId = id ? normalizeTodoId(id) : \"\";\n\t\t\tconst title = typeof args.title === \"string\" ? args.title : \"\";\n\t\t\tlet text = theme.fg(\"toolTitle\", theme.bold(\"todo \")) + theme.fg(\"muted\", action);\n\t\t\tif (normalizedId) {\n\t\t\t\ttext += \" \" + theme.fg(\"accent\", formatTodoId(normalizedId));\n\t\t\t}\n\t\t\tif (title) {\n\t\t\t\ttext += \" \" + theme.fg(\"dim\", `\"${title}\"`);\n\t\t\t}\n\t\t\treturn new Text(text, 0, 0);\n\t\t},\n\n\t\trenderResult(result, { expanded, isPartial }, theme) {\n\t\t\tconst details = result.details as TodoToolDetails | undefined;\n\t\t\tif (isPartial) {\n\t\t\t\treturn new Text(theme.fg(\"warning\", \"Processing...\"), 0, 0);\n\t\t\t}\n\t\t\tif (!details) {\n\t\t\t\tconst text = result.content[0];\n\t\t\t\treturn new Text(text?.type === \"text\" ? text.text : \"\", 0, 0);\n\t\t\t}\n\n\t\t\tif (details.error) {\n\t\t\t\treturn new Text(theme.fg(\"error\", `Error: ${details.error}`), 0, 0);\n\t\t\t}\n\n\t\t\tif (details.action === \"list\" || details.action === \"list-all\") {\n\t\t\t\tlet text = renderTodoList(theme, details.todos, expanded, details.currentSessionId);\n\t\t\t\tif (!expanded) {\n\t\t\t\t\tconst { closedTodos } = splitTodosByAssignment(details.todos);\n\t\t\t\t\tif (closedTodos.length) {\n\t\t\t\t\t\ttext = appendExpandHint(theme, text);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn new Text(text, 0, 0);\n\t\t\t}\n\n\t\t\tif (!(\"todo\" in details) || !details.todo) {\n\t\t\t\tconst text = result.content[0];\n\t\t\t\treturn new Text(text?.type === \"text\" ? text.text : \"\", 0, 0);\n\t\t\t}\n\n\t\t\tlet text = renderTodoDetail(theme, details.todo, expanded);\n\t\t\tconst actionLabel =\n\t\t\t\tdetails.action === \"create\"\n\t\t\t\t\t? \"Created\"\n\t\t\t\t\t: details.action === \"update\"\n\t\t\t\t\t\t? \"Updated\"\n\t\t\t\t\t\t: details.action === \"append\"\n\t\t\t\t\t\t\t? \"Appended to\"\n\t\t\t\t\t\t\t: details.action === \"delete\"\n\t\t\t\t\t\t\t\t? \"Deleted\"\n\t\t\t\t\t\t\t\t: details.action === \"claim\"\n\t\t\t\t\t\t\t\t\t? \"Claimed\"\n\t\t\t\t\t\t\t\t\t: details.action === \"release\"\n\t\t\t\t\t\t\t\t\t\t? \"Released\"\n\t\t\t\t\t\t\t\t\t\t: null;\n\t\t\tif (actionLabel) {\n\t\t\t\tconst lines = text.split(\"\\n\");\n\t\t\t\tlines[0] = theme.fg(\"success\", \"✓ \") + theme.fg(\"muted\", `${actionLabel} `) + lines[0];\n\t\t\t\ttext = lines.join(\"\\n\");\n\t\t\t}\n\t\t\tif (!expanded) {\n\t\t\t\ttext = appendExpandHint(theme, text);\n\t\t\t}\n\t\t\treturn new Text(text, 0, 0);\n\t\t},\n\t};\n}\n"]}

package/dist/core/tools/todos.js

@@ -571,6 +571,9 @@ async function deleteTodo(todosDir, id, ctx) {
     }
     return result;
 }
+export const DEFAULT_PROMPT_GUIDANCE = [
+    "**To-do management**: If the user has a complex task that can be broken down into actionable steps, use the `todo` tool to create a task list before proceeding. This ensures clarity and alignment with the user's goals and that you have a way to track your work and ensure you are meeting the user's expectations.",
+];
 export function createTodoToolDefinition(cwd = process.cwd()) {
     const todosDirLabel = getTodosDirLabel(cwd);
     return {
@@ -581,6 +584,7 @@ export function createTodoToolDefinition(cwd = process.cwd()) {
             "Todo ids are shown as TODO-<hex>; id parameters accept TODO-<hex> or the raw hex filename. " +
             "Claim tasks before working on them to avoid conflicts, and close them when complete.",
         parameters: TodoParams,
+        promptGuidelines: DEFAULT_PROMPT_GUIDANCE,
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const todosDir = getTodosDir(ctx.cwd);
             const action = params.action;