ai-prompt-guide-mcp 1.0.0

package/dist/tools/implementations/start-coordinator-task.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Implementation for the start_coordinator_task tool
+ *
+ * Start work on coordinator task (sequential mode ONLY)
+ *
+ * - Finds next pending task automatically
+ * - Injects Main-Workflow from first task
+ * - Loads task-specific Workflow
+ * - Loads hierarchical references
+ */
+import type { SessionState } from '../../session/types.js';
+import type { DocumentManager } from '../../document-manager.js';
+import type { WorkflowPrompt } from '../../prompts/workflow-prompts.js';
+import type { HierarchicalContent } from '../../shared/reference-loader.js';
+/**
+ * Response interface for start_coordinator_task tool
+ */
+export interface StartCoordinatorTaskResponse {
+    document: string;
+    task: {
+        slug: string;
+        title: string;
+        content: string;
+        status: string;
+        full_path: string;
+        workflow?: WorkflowPrompt;
+        main_workflow?: WorkflowPrompt;
+        referenced_documents?: HierarchicalContent[];
+    };
+}
+/**
+ * Start work on coordinator task with optional context injection
+ *
+ * VALIDATION: Sequential only (no #slug allowed), enforces /coordinator/ namespace
+ *
+ * @param args - Tool arguments (return_task_context optional, defaults to false)
+ * @param _state - Session state (unused but required by tool signature)
+ * @param manager - Document manager for accessing documents
+ * @returns Promise resolving to task data (minimal or enriched based on return_task_context)
+ * @throws {AddressingError} When parameters are invalid or task validation fails
+ * @throws {DocumentNotFoundError} When document doesn't exist
+ */
+export declare function startCoordinatorTask(args: Record<string, unknown>, _state: SessionState, manager: DocumentManager): Promise<StartCoordinatorTaskResponse>;
+//# sourceMappingURL=start-coordinator-task.d.ts.map

package/dist/tools/implementations/start-coordinator-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-coordinator-task.d.ts","sourceRoot":"","sources":["../../../src/tools/implementations/start-coordinator-task.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAUjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAKxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAG5E;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,cAAc,CAAC;QAC1B,aAAa,CAAC,EAAE,cAAc,CAAC;QAC/B,oBAAoB,CAAC,EAAE,mBAAmB,EAAE,CAAC;KAC9C,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,4BAA4B,CAAC,CA8HvC"}

package/dist/tools/implementations/start-coordinator-task.js

@@ -0,0 +1,125 @@
+/**
+ * Implementation for the start_coordinator_task tool
+ *
+ * Start work on coordinator task (sequential mode ONLY)
+ *
+ * - Finds next pending task automatically
+ * - Injects Main-Workflow from first task
+ * - Loads task-specific Workflow
+ * - Loads hierarchical references
+ */
+import { AddressingError, DocumentNotFoundError } from '../../shared/addressing-system.js';
+import { validateCoordinatorTaskAccess } from '../../shared/task-validation.js';
+import { enrichTaskWithWorkflow, enrichTaskWithMainWorkflow } from '../../shared/workflow-prompt-utilities.js';
+import { enrichTaskWithReferences, findNextAvailableTask } from '../../shared/task-view-utilities.js';
+import { PATH_PREFIXES, toUserPath } from '../../shared/namespace-constants.js';
+/**
+ * Start work on coordinator task with optional context injection
+ *
+ * VALIDATION: Sequential only (no #slug allowed), enforces /coordinator/ namespace
+ *
+ * @param args - Tool arguments (return_task_context optional, defaults to false)
+ * @param _state - Session state (unused but required by tool signature)
+ * @param manager - Document manager for accessing documents
+ * @returns Promise resolving to task data (minimal or enriched based on return_task_context)
+ * @throws {AddressingError} When parameters are invalid or task validation fails
+ * @throws {DocumentNotFoundError} When document doesn't exist
+ */
+export async function startCoordinatorTask(args, _state, manager) {
+    try {
+        // Extract return_task_context parameter (default: false)
+        const returnTaskContext = args['return_task_context'] ?? false;
+        // COORDINATOR-SPECIFIC: Fixed document path using explicit path prefix
+        const documentPath = `${PATH_PREFIXES.COORDINATOR}active.md`;
+        // Validate coordinator access (reject if #slug provided)
+        const documentParam = args['document'];
+        // eslint-disable-next-line @typescript-eslint/prefer-optional-chain
+        if (documentParam != null && documentParam.includes('#')) {
+            const taskSlug = documentParam.split('#')[1];
+            validateCoordinatorTaskAccess(documentPath, taskSlug); // Will throw error
+        }
+        else {
+            validateCoordinatorTaskAccess(documentPath, undefined);
+        }
+        // Load document
+        const document = await manager.getDocument(documentPath);
+        if (document == null) {
+            throw new DocumentNotFoundError(documentPath);
+        }
+        // Find next task (sequential mode - SHARED utility)
+        const nextTask = await findNextAvailableTask(manager, document, undefined);
+        if (nextTask == null) {
+            throw new AddressingError('No available tasks in coordinator document', 'NO_AVAILABLE_TASKS', {
+                document: documentPath,
+                suggestion: 'Create tasks using coordinator_task tool'
+            });
+        }
+        const targetTaskSlug = nextTask.slug;
+        // User-facing paths use relative format
+        const userDocumentPath = toUserPath(documentPath);
+        const fullPath = `${userDocumentPath}#${targetTaskSlug}`;
+        // MINIMAL RESPONSE: Return basic task info without context
+        if (!returnTaskContext) {
+            return {
+                document: userDocumentPath,
+                task: {
+                    slug: targetTaskSlug,
+                    title: nextTask.title,
+                    content: '', // Empty content when not returning context
+                    status: nextTask.status,
+                    full_path: fullPath
+                }
+            };
+        }
+        // FULL CONTEXT: Load and enrich with workflows and references
+        const taskContent = await manager.getSectionContent(documentPath, targetTaskSlug);
+        if (taskContent == null) {
+            throw new AddressingError(`Task content not found for ${targetTaskSlug}`, 'TASK_CONTENT_NOT_FOUND', {
+                document: documentPath,
+                task: targetTaskSlug
+            });
+        }
+        // WORKFLOW ENRICHMENT (shared utilities)
+        // Step 1: Start with reference enrichment (returns full TaskViewData)
+        const withReferences = await enrichTaskWithReferences(manager, documentPath, targetTaskSlug, taskContent);
+        // Step 2: Add task-specific workflow (preserves all existing fields)
+        const withWorkflow = enrichTaskWithWorkflow(withReferences, taskContent);
+        // Step 3: Add main workflow (preserves all existing fields including workflow and references)
+        const fullyEnriched = await enrichTaskWithMainWorkflow(manager, document, withWorkflow);
+        // Extract workflow data with explicit typing for response
+        const workflow = 'workflow' in fullyEnriched
+            ? fullyEnriched.workflow
+            : undefined;
+        const mainWorkflow = 'mainWorkflow' in fullyEnriched
+            ? fullyEnriched.mainWorkflow
+            : undefined;
+        // ENRICHED RESPONSE - spread all enriched data
+        return {
+            document: userDocumentPath,
+            task: {
+                slug: fullyEnriched.slug,
+                title: fullyEnriched.title,
+                content: fullyEnriched.content,
+                status: fullyEnriched.status,
+                full_path: fullPath,
+                ...(workflow != null && { workflow }),
+                ...(mainWorkflow != null && { main_workflow: mainWorkflow }),
+                ...(fullyEnriched.referencedDocuments != null &&
+                    fullyEnriched.referencedDocuments.length > 0 && {
+                    referenced_documents: fullyEnriched.referencedDocuments
+                })
+            }
+        };
+    }
+    catch (error) {
+        // Re-throw known error types
+        if (error instanceof AddressingError || error instanceof DocumentNotFoundError) {
+            throw error;
+        }
+        // Wrap unexpected errors
+        throw new AddressingError(`Failed to start coordinator task: ${error instanceof Error ? error.message : String(error)}`, 'START_COORDINATOR_TASK_FAILED', {
+            originalError: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+//# sourceMappingURL=start-coordinator-task.js.map

package/dist/tools/implementations/start-coordinator-task.js.map

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

package/dist/tools/implementations/start-subagent-task.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Implementation for the start_subagent_task tool
+ *
+ * Signals "I'm starting work on this task" and provides FULL CONTEXT including:
+ * - Task-specific workflow (if present in task metadata)
+ * - Referenced documents (hierarchical @reference loading)
+ *
+ * AD-HOC MODE ONLY:
+ * - REQUIRES #slug (format: /docs/path.md#task-slug)
+ * - Works exclusively with /docs/ namespace
+ * - Task workflow only (NO main workflow injection)
+ *
+ * This tool is used for:
+ * - Starting work on an assigned subagent task
+ * - Resuming work after context compression
+ *
+ * Unlike view_subagent_task (passive inspection) or complete_subagent_task (work continuation),
+ * start_subagent_task provides full workflow injection for new/resumed sessions.
+ */
+import type { SessionState } from '../../session/types.js';
+import type { DocumentManager } from '../../document-manager.js';
+import type { WorkflowPrompt } from '../../prompts/workflow-prompts.js';
+import type { HierarchicalContent } from '../../shared/reference-loader.js';
+/**
+ * Response interface for start_subagent_task tool
+ * Ad-hoc mode only - task workflow only, NO main workflow
+ */
+export interface StartSubagentTaskResponse {
+    document: string;
+    task: {
+        slug: string;
+        title: string;
+        content: string;
+        status: string;
+        full_path: string;
+        workflow?: WorkflowPrompt;
+        referenced_documents?: HierarchicalContent[];
+    };
+}
+/**
+ * Start work on a subagent task with full context injection
+ *
+ * AD-HOC MODE ONLY: Requires #slug, enforces /docs/ namespace
+ *
+ * @param args - Tool arguments containing document path with task slug (format: /docs/path.md#task-slug)
+ * @param _state - Session state (unused but required by tool signature)
+ * @param manager - Document manager for accessing documents
+ * @returns Promise resolving to enriched task data with task workflow and references (NO main workflow)
+ * @throws {AddressingError} When parameters are invalid or task validation fails
+ * @throws {DocumentNotFoundError} When document doesn't exist
+ */
+export declare function startSubagentTask(args: Record<string, unknown>, _state: SessionState, manager: DocumentManager): Promise<StartSubagentTaskResponse>;
+//# sourceMappingURL=start-subagent-task.d.ts.map

package/dist/tools/implementations/start-subagent-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-subagent-task.d.ts","sourceRoot":"","sources":["../../../src/tools/implementations/start-subagent-task.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAajE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAG5E;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,cAAc,CAAC;QAC1B,oBAAoB,CAAC,EAAE,mBAAmB,EAAE,CAAC;KAC9C,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,yBAAyB,CAAC,CA4MpC"}

package/dist/tools/implementations/start-subagent-task.js

@@ -0,0 +1,179 @@
+/**
+ * Implementation for the start_subagent_task tool
+ *
+ * Signals "I'm starting work on this task" and provides FULL CONTEXT including:
+ * - Task-specific workflow (if present in task metadata)
+ * - Referenced documents (hierarchical @reference loading)
+ *
+ * AD-HOC MODE ONLY:
+ * - REQUIRES #slug (format: /docs/path.md#task-slug)
+ * - Works exclusively with /docs/ namespace
+ * - Task workflow only (NO main workflow injection)
+ *
+ * This tool is used for:
+ * - Starting work on an assigned subagent task
+ * - Resuming work after context compression
+ *
+ * Unlike view_subagent_task (passive inspection) or complete_subagent_task (work continuation),
+ * start_subagent_task provides full workflow injection for new/resumed sessions.
+ */
+import { ToolIntegration, AddressingError, DocumentNotFoundError } from '../../shared/addressing-system.js';
+import { validateSubagentTaskAccess } from '../../shared/task-validation.js';
+import { enrichTaskWithReferences, extractTaskField } from '../../shared/task-view-utilities.js';
+import { enrichTaskWithWorkflow } from '../../shared/workflow-prompt-utilities.js';
+import { getTaskHeadings } from '../../shared/task-utilities.js';
+/**
+ * Start work on a subagent task with full context injection
+ *
+ * AD-HOC MODE ONLY: Requires #slug, enforces /docs/ namespace
+ *
+ * @param args - Tool arguments containing document path with task slug (format: /docs/path.md#task-slug)
+ * @param _state - Session state (unused but required by tool signature)
+ * @param manager - Document manager for accessing documents
+ * @returns Promise resolving to enriched task data with task workflow and references (NO main workflow)
+ * @throws {AddressingError} When parameters are invalid or task validation fails
+ * @throws {DocumentNotFoundError} When document doesn't exist
+ */
+export async function startSubagentTask(args, _state, manager) {
+    try {
+        // ===== INPUT VALIDATION =====
+        const documentParam = ToolIntegration.validateStringParameter(args['document'], 'document');
+        // Parse document path and task slug (ad-hoc mode only)
+        if (!documentParam.includes('#')) {
+            throw new AddressingError('Subagent tasks require #slug (ad-hoc mode). Use coordinator tools for sequential work.', 'SUBAGENT_REQUIRES_SLUG', {
+                suggestion: 'Format: /docs/path.md#task-slug',
+                coordinator_alternative: 'Use start_coordinator_task for sequential work'
+            });
+        }
+        const parts = documentParam.split('#');
+        const docPath = parts[0] ?? documentParam;
+        const taskSlug = parts[1];
+        if (taskSlug == null || taskSlug === '') {
+            throw new AddressingError('Task slug cannot be empty after #', 'EMPTY_TASK_SLUG');
+        }
+        // ===== SUBAGENT-SPECIFIC VALIDATION =====
+        // Enforce ad-hoc mode with #slug and /docs/ namespace
+        validateSubagentTaskAccess(docPath, taskSlug);
+        // ===== ADDRESS PARSING =====
+        const { addresses } = ToolIntegration.validateAndParse({
+            document: docPath,
+            task: taskSlug
+        });
+        // ===== DOCUMENT LOADING =====
+        const document = await manager.getDocument(addresses.document.path);
+        if (document == null) {
+            throw new DocumentNotFoundError(addresses.document.path);
+        }
+        // ===== TASK VALIDATION =====
+        // Find tasks section
+        const tasksSection = document.headings.find(h => h.slug === 'tasks' || h.title.toLowerCase() === 'tasks');
+        if (tasksSection == null) {
+            throw new AddressingError('No tasks section found in document', 'NO_TASKS_SECTION', {
+                document: addresses.document.path,
+                available_sections: document.headings.map(h => h.slug)
+            });
+        }
+        // ===== TASK RESOLUTION (AD-HOC MODE ONLY) =====
+        // Use the provided task slug directly
+        if (addresses.task == null) {
+            throw new AddressingError('Task address is required in ad-hoc mode', 'MISSING_TASK_ADDRESS');
+        }
+        const taskAddress = addresses.task;
+        const tasksIndex = document.headings.findIndex(h => h.slug === tasksSection.slug);
+        const taskIndex = document.headings.findIndex(h => h.slug === taskAddress.slug);
+        // Check if task exists after tasks section and is deeper than tasks section
+        const taskHeading = document.headings[taskIndex];
+        const isUnderTasksSection = taskIndex > tasksIndex &&
+            taskHeading != null &&
+            taskHeading.depth > tasksSection.depth;
+        if (!isUnderTasksSection) {
+            // Build list of available tasks for helpful error message
+            const taskHeadings = await getTaskHeadings(document, tasksSection);
+            throw new AddressingError(`Task not found: ${taskAddress.slug}`, 'TASK_NOT_FOUND', {
+                document: addresses.document.path,
+                task: taskAddress.slug,
+                available_tasks: taskHeadings.map(h => h.slug)
+            });
+        }
+        // Check if the next heading at same or shallower depth is still under tasks section
+        // This ensures we haven't gone past the tasks section boundary
+        let withinTasksSection = true;
+        for (let i = taskIndex + 1; i < document.headings.length; i++) {
+            const nextHeading = document.headings[i];
+            if (nextHeading != null && nextHeading.depth <= tasksSection.depth) {
+                // Hit a heading at same or shallower depth as tasks section
+                withinTasksSection = true;
+                break;
+            }
+        }
+        if (!withinTasksSection) {
+            throw new AddressingError(`Section ${taskAddress.slug} is not under tasks section`, 'NOT_A_TASK', {
+                document: addresses.document.path,
+                section: taskAddress.slug
+            });
+        }
+        const targetTaskSlug = taskAddress.slug;
+        // ===== TASK CONTENT LOADING =====
+        const taskContent = await manager.getSectionContent(addresses.document.path, targetTaskSlug);
+        if (taskContent == null) {
+            throw new AddressingError(`Task content not found for ${targetTaskSlug}`, 'TASK_CONTENT_NOT_FOUND', {
+                document: addresses.document.path,
+                task: targetTaskSlug
+            });
+        }
+        // ===== BASE TASK DATA EXTRACTION =====
+        const heading = document.headings.find(h => h.slug === targetTaskSlug);
+        const title = heading?.title ?? targetTaskSlug;
+        const status = extractTaskField(taskContent, 'Status') ?? 'pending';
+        // Build base task data
+        const baseTaskData = {
+            slug: targetTaskSlug,
+            title,
+            content: taskContent,
+            status
+        };
+        // ===== WORKFLOW ENRICHMENT (AD-HOC MODE ONLY) =====
+        // Enrich with task-specific workflow (if present in task metadata)
+        // Ad-hoc mode: task workflow only, NO main workflow injection
+        const taskWithWorkflow = enrichTaskWithWorkflow(baseTaskData, taskContent);
+        // ===== REFERENCE ENRICHMENT =====
+        // Enrich with hierarchical references from task content
+        const enrichedTask = await enrichTaskWithReferences(manager, addresses.document.path, targetTaskSlug, taskContent, heading, taskAddress);
+        // Merge workflow data with reference-enriched data
+        // Extract task workflow (ad-hoc mode: NO main workflow)
+        const workflow = 'workflow' in taskWithWorkflow
+            ? taskWithWorkflow.workflow
+            : undefined;
+        const fullyEnriched = {
+            ...enrichedTask,
+            ...(workflow != null && { workflow })
+        };
+        // ===== OUTPUT CONSTRUCTION =====
+        return {
+            document: addresses.document.path,
+            task: {
+                slug: fullyEnriched.slug,
+                title: fullyEnriched.title,
+                content: fullyEnriched.content,
+                status: fullyEnriched.status,
+                full_path: fullyEnriched.fullPath ?? ToolIntegration.formatTaskPath(taskAddress),
+                ...(workflow != null && { workflow }),
+                ...(fullyEnriched.referencedDocuments != null &&
+                    fullyEnriched.referencedDocuments.length > 0 && {
+                    referenced_documents: fullyEnriched.referencedDocuments
+                })
+            }
+        };
+    }
+    catch (error) {
+        // Re-throw known error types
+        if (error instanceof AddressingError || error instanceof DocumentNotFoundError) {
+            throw error;
+        }
+        // Wrap unexpected errors
+        throw new AddressingError(`Failed to start task: ${error instanceof Error ? error.message : String(error)}`, 'START_TASK_FAILED', {
+            originalError: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+//# sourceMappingURL=start-subagent-task.js.map

package/dist/tools/implementations/start-subagent-task.js.map

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

package/dist/tools/implementations/start-task.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Implementation for the start_task tool
+ *
+ * Signals "I'm starting work on this task" and provides FULL CONTEXT including:
+ * - Task-specific workflow (if present in task metadata)
+ * - Main workflow from first task (if present in first task metadata)
+ * - Referenced documents (hierarchical @reference loading)
+ *
+ * This tool is used for:
+ * - Starting work on a task (new session)
+ * - Resuming work after context compression
+ *
+ * Unlike view_task (passive inspection) or complete_task (work continuation),
+ * start_task provides full workflow injection for new/resumed sessions.
+ */
+import type { SessionState } from '../../session/types.js';
+import type { DocumentManager } from '../../document-manager.js';
+import type { WorkflowPrompt } from '../../prompts/workflow-prompts.js';
+import type { HierarchicalContent } from '../../shared/reference-loader.js';
+/**
+ * Response interface for start_task tool
+ */
+export interface StartTaskResponse {
+    mode: 'sequential' | 'adhoc';
+    document: string;
+    task: {
+        slug: string;
+        title: string;
+        content: string;
+        status: string;
+        full_path: string;
+        workflow?: WorkflowPrompt;
+        main_workflow?: WorkflowPrompt;
+        referenced_documents?: HierarchicalContent[];
+    };
+}
+/**
+ * Start work on a task with full context injection
+ *
+ * @param args - Tool arguments containing document path (and optional task slug after #)
+ * @param _state - Session state (unused but required by tool signature)
+ * @param manager - Document manager for accessing documents
+ * @returns Promise resolving to enriched task data with full workflow context
+ * @throws {AddressingError} When parameters are invalid or task validation fails
+ * @throws {DocumentNotFoundError} When document doesn't exist
+ */
+export declare function startTask(args: Record<string, unknown>, _state: SessionState, manager: DocumentManager): Promise<StartTaskResponse>;
+//# sourceMappingURL=start-task.d.ts.map

package/dist/tools/implementations/start-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-task.d.ts","sourceRoot":"","sources":["../../../src/tools/implementations/start-task.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAejE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAG5E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,cAAc,CAAC;QAC1B,aAAa,CAAC,EAAE,cAAc,CAAC;QAC/B,oBAAoB,CAAC,EAAE,mBAAmB,EAAE,CAAC;KAC9C,CAAC;CACH;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,iBAAiB,CAAC,CA+P5B"}