tuplet 2.7.0

package/dist/tools/sub-agent.js

@@ -0,0 +1,312 @@
+/**
+ * Task Tool
+ *
+ * Tool for spawning sub-agents to handle complex operations.
+ */
+import { OUTPUT_TOOL_NAME, createOutputTool } from "./output.js";
+/**
+ * Build description for agent in __sub_agent__ tool
+ */
+function buildAgentDescription(agent) {
+    let desc = `- **${agent.name}**: ${agent.description}`;
+    if (agent.inputSchema?.properties) {
+        const props = agent.inputSchema.properties;
+        const paramList = Object.entries(props)
+            .map(([name, schema]) => `${name}: ${schema.description || schema.type || "any"}`)
+            .join(", ");
+        desc += `\n  Parameters: { ${paramList} }`;
+    }
+    if (agent.outputSchema) {
+        desc += `\n  Returns: structured data (summary + data object)`;
+    }
+    const toolNames = [
+        ...agent.tools.map((t) => t.name),
+        ...(agent.builtInToolNames || []),
+    ];
+    desc += `\n  Tools: ${toolNames.length > 0 ? toolNames.join(", ") : "none"}`;
+    return desc;
+}
+/**
+ * Create a wrapper logger that prefixes sub-agent logs
+ */
+function createSubLogger(parentLogger, agentName) {
+    if (!parentLogger)
+        return undefined;
+    return {
+        ...parentLogger,
+        debug: (msg, data) => parentLogger.debug?.(`[${agentName}] ${msg}`, data),
+        info: (msg, data) => parentLogger.info?.(`[${agentName}] ${msg}`, data),
+        warn: (msg, data) => parentLogger.warn?.(`[${agentName}] ${msg}`, data),
+        error: (msg, data) => parentLogger.error?.(`[${agentName}] ${msg}`, data),
+        onToolCall: (toolName, toolParams) => {
+            parentLogger.info?.(`[${agentName}] Tool: ${toolName}`);
+            parentLogger.onToolCall?.(toolName, toolParams);
+        },
+        onToolResult: (toolName, result, durationMs) => {
+            const status = result.success ? "OK" : "ERROR";
+            parentLogger.info?.(`[${agentName}] Tool ${toolName}: ${status} (${durationMs}ms)`);
+            parentLogger.onToolResult?.(toolName, result, durationMs);
+        },
+        onProgress: (update) => {
+            // Prefix sub-agent progress messages
+            parentLogger.onProgress?.({
+                ...update,
+                message: `[${agentName}] ${update.message}`,
+            });
+        },
+        onTodoUpdate: (update) => {
+            // Forward sub-agent todo updates with agent name set
+            parentLogger.onTodoUpdate?.({
+                ...update,
+                agentName: agentName,
+            });
+        },
+    };
+}
+/**
+ * Create the __sub_agent__ tool for spawning sub-agents
+ */
+export function createTaskTool(context, agents, createSubTuplet) {
+    const agentNames = agents.map((a) => a.name);
+    const agentDescriptions = agents.map(buildAgentDescription).join("\n");
+    // Build combined properties from all agents
+    // Runtime validation will check agent-specific requirements
+    const combinedProperties = {
+        agent: {
+            type: "string",
+            enum: agentNames,
+            description: "Which agent to spawn",
+        },
+    };
+    // Add properties from all agent inputSchemas
+    for (const agent of agents) {
+        if (agent.inputSchema?.properties) {
+            const props = agent.inputSchema.properties;
+            for (const [key, schema] of Object.entries(props)) {
+                if (!combinedProperties[key]) {
+                    combinedProperties[key] = {
+                        type: schema.type || "string",
+                        description: `[${agent.name}] ${schema.description || ""}`,
+                    };
+                }
+            }
+        }
+    }
+    const toolName = "__sub_agent__";
+    return {
+        name: toolName,
+        description: `The ${toolName} tool activates specialized agents designed to autonomously execute complex operations. Each agent variant possesses distinct capabilities and has access to specific tools.
+
+Agent types available and their associated tools:
+${agentDescriptions}
+
+When invoking the ${toolName} tool, you must provide a subagent_type parameter to designate which agent variant to utilize.
+
+Key considerations:
+- Include a brief description (3-5 words) that summarizes the agent's objective
+- Upon completion, the agent returns a single message to you. This result is not displayed to the user. To share the outcome with the user, send a text message containing a concise summary of what was accomplished.
+- Upon completion, the agent provides both a message and its agent ID. You can leverage this ID to reactivate the agent for subsequent related work.
+- Act as a lead: provide each agent with a clear brief — what to accomplish, relevant context from your exploration, constraints, and how to verify success. Structured input produces better results than vague instructions.
+- Agents marked as having "access to current context" can view the complete conversation history preceding the tool invocation. With these agents, you can write abbreviated prompts that reference prior context (e.g., "analyze the issue mentioned earlier") rather than duplicating information. The agent receives all previous messages and comprehends the context.
+- Generally, trust the agent's output
+- Explicitly inform the agent whether it should create content or conduct research (searching, reading documents, fetching information, etc.), as it cannot infer the user's intentions
+- If an agent description indicates it should be utilized proactively, attempt to deploy it without waiting for an explicit user request. Apply discretion.
+
+Example usage:
+
+<example_agent_descriptions>
+"travel-planner": deploy this agent after gathering the user's travel preferences and requirements
+"welcome-handler": deploy this agent to reply to user greetings with an amusing quip
+</example_agent_description>
+
+<example>
+user: "I need help planning a 5-day trip to Tokyo in spring. I love art museums and local cuisine."
+assistant: I'll help you plan a comprehensive Tokyo itinerary
+assistant: First, let me gather information about spring activities and create a day-by-day plan
+assistant: I'm creating the following itinerary outline:
+<plan>
+Day 1: Arrival and Shibuya exploration
+Day 2: Ueno Park museums (Tokyo National Museum, National Museum of Western Art)
+Day 3: TeamLab Borderless, Odaiba waterfront
+Day 4: Tsukiji Outer Market food tour, Ginza art galleries
+Day 5: Meiji Shrine, Harajuku, departure preparation
+</plan>
+<commentary>
+Since a detailed travel plan has been created, now deploy the travel-planner agent to add specific restaurant recommendations, booking details, and transportation information
+</commentary>
+assistant: Let me now employ the travel-planner agent to enhance this itinerary with detailed logistics
+assistant: Invokes the __sub_agent__ tool to activate the travel-planner agent
+</example>
+
+<example>
+user: "Hello"
+<commentary>
+The user has initiated a greeting, so deploy the welcome-handler agent to provide a friendly response
+</commentary>
+assistant: "I'll invoke the __sub_agent__ tool to activate the welcome-handler agent"
+</example>
+`,
+        parameters: {
+            type: "object",
+            properties: combinedProperties,
+            required: ["agent"],
+        },
+        execute: async (params, toolCtx) => {
+            const { agent: agentName, ...inputParams } = params;
+            const agentConfig = agents.find((a) => a.name === agentName);
+            if (!agentConfig) {
+                return { success: false, error: `Unknown agent: ${agentName}` };
+            }
+            // Build the input message for the sub-agent
+            const inputMessage = `Task parameters:\n${JSON.stringify(inputParams, null, 2)}`;
+            // Log sub-agent start
+            context.config.logger?.info(`[Sub-Agent: ${agentName}] Starting...`);
+            context.config.logger?.debug(`[Sub-Agent: ${agentName}] Input: ${inputMessage.slice(0, 200)}${inputMessage.length > 200 ? "..." : ""}`);
+            // Progress: sub-agent starting
+            context.config.logger?.onProgress?.({
+                type: "sub_agent_start",
+                message: `Starting ${agentName}...`,
+                details: { agentName },
+            });
+            try {
+                // Create a wrapper logger that prefixes sub-agent logs
+                const subLogger = createSubLogger(context.config.logger, agentName);
+                // Use agent-specific LLM/model or fall back to parent's
+                const subLlm = agentConfig.llm || context.config.llm;
+                // Build sub-agent tools - include __output__ if outputSchema is defined
+                const subTools = agentConfig.outputSchema
+                    ? [...agentConfig.tools, createOutputTool(agentConfig.outputSchema)]
+                    : agentConfig.tools;
+                // Get parent's trace builder for nested tracing
+                const parentTraceBuilder = context.getCurrentTraceBuilder();
+                // Start sub-agent span in trace
+                if (parentTraceBuilder) {
+                    parentTraceBuilder.startSubAgent(agentName, inputMessage);
+                }
+                const subTuplet = createSubTuplet({
+                    role: agentConfig.name,
+                    _systemPrompt: `Today's date is ${new Date().toISOString().split('T')[0]}.\n\n${agentConfig.systemPrompt}`,
+                    tools: subTools,
+                    llm: subLlm,
+                    logger: subLogger,
+                    maxIterations: agentConfig.maxIterations || context.config.maxIterations,
+                    disableAskUser: agentConfig.disableAskUser ?? false,
+                    // Pass parent's trace config for nested sub-agents
+                    trace: context.config.trace,
+                    agentName: agentName,
+                    // Prevent recursive agent injection — sub-agents don't get their own sub-agents
+                    agents: [],
+                });
+                const result = await subTuplet.run(inputMessage, {
+                    // Pass trace builder for nested tracing
+                    _traceBuilder: parentTraceBuilder,
+                    // Pass workspace to sub-agent so its tools receive the same workspace
+                    conversationId: toolCtx.conversationId,
+                    userId: toolCtx.userId,
+                    // Pass workspace so sub-agent can read/write to same workspace
+                    workspace: toolCtx.workspace,
+                });
+                // End sub-agent span in trace
+                if (parentTraceBuilder) {
+                    const status = result.status === "complete"
+                        ? "complete"
+                        : result.status === "interrupted"
+                            ? "interrupted"
+                            : "error";
+                    parentTraceBuilder.endSubAgent(status, result.response);
+                }
+                // Log sub-agent completion with details
+                context.config.logger?.info(`[Sub-Agent: ${agentName}] Completed with status: ${result.status}`);
+                context.config.logger?.debug(`[Sub-Agent: ${agentName}] Tool calls: ${result.toolCalls.length}`, result.toolCalls.map((tc) => tc.name));
+                context.config.logger?.debug(`[Sub-Agent: ${agentName}] Response length: ${result.response?.length || 0}`);
+                if (result.response) {
+                    context.config.logger?.debug(`[Sub-Agent: ${agentName}] Response preview: ${result.response.slice(0, 200)}${result.response.length > 200 ? "..." : ""}`);
+                }
+                if (result.thinking && result.thinking.length > 0) {
+                    context.config.logger?.debug(`[Sub-Agent: ${agentName}] Thinking blocks: ${result.thinking.length}`);
+                }
+                // Progress: sub-agent completed
+                context.config.logger?.onProgress?.({
+                    type: "sub_agent_end",
+                    message: `${agentName} completed`,
+                    details: { agentName, success: true },
+                });
+                if (result.status === "needs_input") {
+                    context.config.logger?.debug(`[Sub-Agent: ${agentName}] Returning: needs_input`);
+                    return {
+                        success: false,
+                        error: "Sub-agent needs user input",
+                        data: result.pendingQuestion,
+                    };
+                }
+                if (result.status === "interrupted") {
+                    context.config.logger?.warn(`[Sub-Agent: ${agentName}] Was interrupted: ${result.interrupted?.reason}`);
+                    // Include the agent's last response so the caller can see what was accomplished
+                    const agentResponse = result.response || '';
+                    const hasResponse = agentResponse.length > 0;
+                    return {
+                        success: hasResponse,
+                        error: hasResponse
+                            ? `Sub-agent reached iteration limit but produced output`
+                            : `Sub-agent was interrupted: ${result.interrupted?.reason || "unknown"}`,
+                        data: {
+                            reason: result.interrupted?.reason,
+                            iterationsCompleted: result.interrupted?.iterationsCompleted,
+                            summary: agentResponse || null,
+                        },
+                    };
+                }
+                // Check if sub-agent used __output__ tool to return structured data
+                const outputCall = result.toolCalls.find((tc) => tc.name === OUTPUT_TOOL_NAME);
+                context.config.logger?.debug(`[Sub-Agent: ${agentName}] __output__ tool used: ${!!outputCall}`);
+                if (outputCall &&
+                    outputCall.output?.success &&
+                    outputCall.output?.data) {
+                    const outputData = outputCall.output.data;
+                    context.config.logger?.debug(`[Sub-Agent: ${agentName}] Returning structured output`, {
+                        summaryLength: outputData.summary?.length || 0,
+                        hasData: outputData.data !== null && outputData.data !== undefined,
+                    });
+                    return {
+                        success: true,
+                        data: {
+                            summary: outputData.summary,
+                            data: outputData.data,
+                        },
+                    };
+                }
+                // Fallback: return response text as summary when __output__ tool wasn't used
+                context.config.logger?.debug(`[Sub-Agent: ${agentName}] Returning text response (no __output__ tool used)`, {
+                    responseLength: result.response?.length || 0,
+                    isEmpty: !result.response,
+                });
+                return {
+                    success: true,
+                    data: {
+                        summary: result.response,
+                        data: null,
+                    },
+                };
+            }
+            catch (error) {
+                // End sub-agent span with error status
+                const parentTraceBuilder = context.getCurrentTraceBuilder();
+                if (parentTraceBuilder) {
+                    parentTraceBuilder.endSubAgent("error");
+                }
+                context.config.logger?.error(`[Sub-Agent: ${agentName}] Failed: ${error instanceof Error ? error.message : String(error)}`);
+                // Progress: sub-agent failed
+                context.config.logger?.onProgress?.({
+                    type: "sub_agent_end",
+                    message: `${agentName} failed`,
+                    details: { agentName, success: false },
+                });
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=sub-agent.js.map

package/dist/tools/sub-agent.js.map

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

package/dist/tools/tasks.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Task Management System (Claude Code 4-Tool Approach)
+ *
+ * Provides task management functionality for agents to track and execute tasks.
+ * Uses 4 separate tools: TaskCreate, TaskUpdate, TaskGet, TaskList
+ */
+import type { Tool, TaskItem, TaskStatus, LogProvider, TaskProgress, TodoItem } from "../types.js";
+import type { Workspace } from "../workspace.js";
+/** Serialized task state for persistence */
+interface TaskManagerState {
+    items: TaskItem[];
+    currentTaskId?: string;
+    nextId: number;
+}
+/**
+ * Format task list for display
+ * @param tasks - Array of tasks to format
+ * @param allTasks - Optional full task list (for checking blocker status). If not provided, blockedBy status won't be resolved.
+ */
+export declare function formatTaskList(tasks: TaskItem[], allTasks?: TaskItem[]): string;
+/** @deprecated Use formatTaskList instead */
+export declare function formatTodoList(todos: TodoItem[]): string;
+/**
+ * TaskManager class for tracking tasks during execution
+ */
+export declare class TaskManager {
+    private items;
+    private currentTaskId?;
+    private nextId;
+    /**
+     * Get all task items
+     */
+    getAll(): TaskItem[];
+    /**
+     * Get a task by ID
+     */
+    get(id: string): TaskItem | undefined;
+    /**
+     * Get current task being worked on
+     */
+    getCurrentTask(): TaskItem | undefined;
+    /**
+     * Check if a task is blocked (has unresolved blockers)
+     */
+    isBlocked(task: TaskItem): boolean;
+    /**
+     * Get open (unresolved) blockers for a task
+     */
+    getOpenBlockers(task: TaskItem): string[];
+    /**
+     * Create a new task
+     * If this is the first task and no tasks are in_progress, auto-starts it (if not blocked)
+     */
+    create(subject: string, description?: string, activeForm?: string, metadata?: Record<string, unknown>): TaskItem;
+    /**
+     * Update a task
+     * Returns the updated task or undefined if not found
+     */
+    update(id: string, updates: {
+        subject?: string;
+        description?: string;
+        activeForm?: string;
+        status?: TaskStatus | 'deleted';
+        owner?: string;
+        metadata?: Record<string, unknown>;
+        addBlocks?: string[];
+        addBlockedBy?: string[];
+        comment?: {
+            author: string;
+            content: string;
+        };
+    }): {
+        task?: TaskItem;
+        deleted?: boolean;
+        next?: TaskItem;
+    };
+    /**
+     * Remove a task ID from all other tasks' blockedBy lists
+     */
+    private removeFromBlockedBy;
+    /**
+     * Remove a task ID from all other tasks' blocks lists
+     */
+    private removeFromBlocks;
+    /**
+     * Find and start the next pending task that is not blocked
+     */
+    private startNextPending;
+    /**
+     * Check if all tasks are completed
+     */
+    isAllCompleted(): boolean;
+    /**
+     * Get progress stats
+     */
+    getProgress(): TaskProgress;
+    /**
+     * Normalize a subject string for duplicate comparison.
+     * Lowercases, strips common filler words, and collapses whitespace.
+     */
+    normalizeSubject(subject: string): string;
+    /**
+     * Find a duplicate among non-completed tasks.
+     * Checks for exact normalized match or substring containment.
+     */
+    findDuplicate(subject: string): TaskItem | undefined;
+    /**
+     * Clear all tasks (used internally)
+     */
+    clear(): void;
+    /**
+     * Serialize the TaskManager state for persistence
+     */
+    serialize(): TaskManagerState;
+    /**
+     * Restore TaskManager state from serialized data
+     */
+    restore(state: TaskManagerState): void;
+    /**
+     * Save tasks to Workspace (if provided)
+     */
+    saveToWorkspace(workspace: Workspace | undefined, agentName?: string): void;
+    /**
+     * Restore tasks from Workspace (if available)
+     * Returns true if tasks were restored
+     */
+    restoreFromWorkspace(workspace: Workspace | undefined): Promise<boolean>;
+}
+/** @deprecated Use TaskManager instead */
+export declare const TodoManager: typeof TaskManager;
+export interface TaskToolOptions {
+    /** Logger for notifying UI about task updates */
+    logger?: LogProvider;
+    /** Agent name (for sub-agents) */
+    agentName?: string;
+    /** Agent ID for ownership checks (defaults to CLAUDE_CODE_AGENT_ID env var) */
+    agentId?: string;
+    /** Agent type for permission checks (defaults to CLAUDE_CODE_AGENT_TYPE env var) */
+    agentType?: 'team-lead' | string;
+    /** Workspace for task persistence across __ask_user__ pauses */
+    workspace?: Workspace;
+}
+/** @deprecated Use TaskToolOptions instead */
+export type TodoToolOptions = TaskToolOptions;
+/**
+ * Create the TaskCreate tool
+ */
+export declare function createTaskCreateTool(manager: TaskManager, options?: TaskToolOptions): Tool;
+/**
+ * Create the TaskUpdate tool
+ */
+export declare function createTaskUpdateTool(manager: TaskManager, options?: TaskToolOptions): Tool;
+/**
+ * Create the TaskGet tool
+ */
+export declare function createTaskGetTool(manager: TaskManager, _options?: TaskToolOptions): Tool;
+/**
+ * Create the TaskList tool
+ */
+export declare function createTaskListTool(manager: TaskManager, options?: TaskToolOptions): Tool;
+/**
+ * Create all 4 task management tools
+ */
+export declare function createTaskTools(manager: TaskManager, options?: TaskToolOptions): Tool[];
+/**
+ * @deprecated Use createTaskTools instead
+ */
+export declare function createTodoTool(manager: TaskManager, options?: TaskToolOptions): Tool;
+export {};
+//# sourceMappingURL=tasks.d.ts.map

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

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