principles-disciple 1.7.4 → 1.7.5

package/dist/tools/agent-spawn.js

@@ -1,456 +0,0 @@
-/**
- * Agent Spawn Tool
- *
- * Provides a tool for spawning subagents with predefined agent definitions.
- * Uses the low-level OpenClaw Subagent API.
- */
-import { Type } from '@sinclair/typebox';
-import * as fs from 'fs';
-import { randomUUID } from 'node:crypto';
-import { loadAgentDefinition, listAvailableAgents } from '../core/agent-loader.js';
-import { resolvePdPath } from '../core/paths.js';
-import { extractEvolutionTaskId, registerEvolutionTaskSession } from '../service/evolution-worker.js';
-import { isSubagentRuntimeAvailable } from '../utils/subagent-probe.js';
-/**
- * Extract assistant text from session messages
- */
-function extractAssistantText(messages) {
-    if (!messages || typeof messages !== 'object')
-        return '';
-    const m = messages;
-    // Try assistantTexts helper first
-    if (m.assistantTexts && Array.isArray(m.assistantTexts)) {
-        return m.assistantTexts.join('\n');
-    }
-    // Fall back to parsing messages array
-    if (m.messages && Array.isArray(m.messages)) {
-        // Find the last assistant message
-        for (let i = m.messages.length - 1; i >= 0; i--) {
-            const msg = m.messages[i];
-            if (msg.role === 'assistant' && msg.content) {
-                if (typeof msg.content === 'string') {
-                    return msg.content;
-                }
-                if (Array.isArray(msg.content)) {
-                    const textParts = msg.content
-                        .filter((c) => c.type === 'text' && c.text)
-                        .map((c) => c.text);
-                    if (textParts.length > 0) {
-                        return textParts.join('\n');
-                    }
-                }
-            }
-        }
-    }
-    return '';
-}
-async function registerDiagnosticianRun(api, task, sessionKey) {
-    const taskId = extractEvolutionTaskId(task);
-    if (!taskId)
-        return;
-    try {
-        const workspaceDir = api.resolvePath('.');
-        const queuePath = resolvePdPath(workspaceDir, 'EVOLUTION_QUEUE');
-        if (!fs.existsSync(queuePath)) {
-            api.logger?.warn?.(`[PD:AgentSpawn] Evolution task ${taskId} not registered because queue file is missing`);
-            return;
-        }
-        await registerEvolutionTaskSession((key) => resolvePdPath(workspaceDir, key), taskId, sessionKey, api.logger);
-    }
-    catch (error) {
-        api.logger?.warn?.(`[PD:AgentSpawn] Failed to register evolution task session: ${String(error)}`);
-    }
-}
-/**
- * Build the full system prompt for a subagent
- * Combines the agent definition with any context-specific additions
- */
-function buildSubagentSystemPrompt(agentDef, _task) {
-    // The systemPrompt from the agent definition is the main content
-    // It will be appended to OpenClaw's minimal subagent prompt
-    return agentDef.systemPrompt;
-}
-const INTERNAL_AGENT_USAGE_GUIDANCE = 'pd_run_worker is only for Principles Disciple internal workers. ' +
-    'Use agents_list / sessions_list / sessions_spawn / sessions_send for peer agents or cross-session communication. ' +
-    'Use subagents to inspect already-dispatched internal workers.';
-function buildInternalAgentUsageMessage(availableAgents) {
-    return [
-        'pd_run_worker is reserved for Principles Disciple internal workers.',
-        `Allowed internal roles: ${availableAgents.join(', ')}`,
-        'Use `agents_list` to discover peer agent ids.',
-        'Use `sessions_spawn` to create or orchestrate another peer session.',
-        'Use `sessions_list` to inspect running peer sessions.',
-        'Use `sessions_send` to talk to another existing session.',
-        'Use `subagents` to inspect already-dispatched internal workers such as diagnostician or explorer.',
-    ].join('\n');
-}
-function looksLikeSessionOrPeerCoordinationTask(task) {
-    const normalized = task.trim().toLowerCase();
-    if (!normalized)
-        return false;
-    const explicitMarkers = [
-        'sessions_send',
-        'sessions_spawn',
-        'sessions_list',
-        'agents_list',
-        'sessionkey',
-        'session key',
-        'sessionid',
-        'session id',
-        'agentid',
-        'agent id',
-        'other session',
-        'another session',
-        'peer agent',
-        'other agent',
-        'another agent',
-        'same-level agent',
-        'same level agent',
-        'cross-session',
-        'cross session',
-        'send a message to',
-        'message another session',
-        'talk to another session',
-        'subagent',
-        'worker status',
-        'running status',
-        'still running',
-        'inspect status',
-        'check status',
-        '同级智能体',
-        '另一个智能体',
-        '其他智能体',
-        '另一个会话',
-        '其他会话',
-        '跨会话',
-        '给另一个会话发消息',
-    ];
-    return explicitMarkers.some((marker) => normalized.includes(marker));
-}
-/**
- * Sanitize params for debug logging (remove sensitive values)
- */
-function sanitizeParamsForLogging(params) {
-    const SENSITIVE_PATTERNS = /password|token|api[_-]?key|secret|credential|authorization|cookie|session/i;
-    const sanitized = {};
-    for (const [key, value] of Object.entries(params)) {
-        if (SENSITIVE_PATTERNS.test(key)) {
-            sanitized[key] = '[REDACTED]';
-        }
-        else if (typeof value === 'string' && value.length > 200) {
-            sanitized[key] = value.slice(0, 200) + '...[truncated]';
-        }
-        else {
-            sanitized[key] = value;
-        }
-    }
-    return sanitized;
-}
-/**
- * Helper to read string parameter from rawParams
- * Supports both camelCase and snake_case parameter names
- */
-function readStringParam(rawParams, key) {
-    const value = rawParams[key];
-    if (typeof value === 'string')
-        return value.trim() || undefined;
-    // Try snake_case alias
-    const snakeKey = key.replace(/([A-Z])/g, '_$1').toLowerCase();
-    const snakeValue = rawParams[snakeKey];
-    if (typeof snakeValue === 'string')
-        return snakeValue.trim() || undefined;
-    return undefined;
-}
-/**
- * Helper to read boolean parameter from rawParams
- * Supports both camelCase and snake_case parameter names
- */
-function readBooleanParam(rawParams, key) {
-    const value = rawParams[key];
-    if (typeof value === 'boolean')
-        return value;
-    // Try snake_case alias
-    const snakeKey = key.replace(/([A-Z])/g, '_$1').toLowerCase();
-    const snakeValue = rawParams[snakeKey];
-    if (typeof snakeValue === 'boolean')
-        return snakeValue;
-    // Backward compatibility for legacy prompt guidance / callers.
-    if (key === 'runInBackground' && typeof rawParams.async === 'boolean') {
-        return rawParams.async;
-    }
-    return undefined;
-}
-/**
- * Create Agent Spawn Tool
- *
- * Uses factory pattern to capture `api` in closure, following OpenClaw plugin SDK conventions.
- * The execute signature must be: async (_toolCallId: string, rawParams: Record<string, unknown>)
- */
-export function createAgentSpawnTool(api) {
-    return {
-        name: 'pd_run_worker',
-        description: `启动指定类型的子智能体执行任务。
-
-可用的智能体类型:
-- explorer: 快速收集证据（文件、日志、复现步骤）
-- diagnostician: 根因分析（verb/adjective + 5Whys）
-- auditor: 演演审计（axiom/system/via-negativa）
-- planner: 制定电影剧本计划
-- implementer: 按计划执行代码修改
-- reviewer: 代码审查（正确性、安全性、可维护性）
-- reporter: 最终汇报（技术细节转管理报告）
-
-示例调用: pd_run_worker(agentType="diagnostician", task="分析 Pain 7386ccfb 的根因")`,
-        parameters: Type.Object({
-            agentType: Type.String({
-                description: '【必填】智能体类型，必须是以下之一: explorer, diagnostician, auditor, planner, implementer, reviewer, reporter',
-            }),
-            task: Type.String({
-                description: '【必填】任务描述，告诉智能体要做什么',
-            }),
-            runInBackground: Type.Optional(Type.Boolean({
-                description: '【可选】是否后台运行。true=立即返回不等待结果，false=等待执行完成。默认 false',
-            })),
-        }),
-        /**
-         * Execution logic for the agent spawn tool
-         *
-         * OpenClaw tool execute signature:
-         * - First parameter: _toolCallId (string) - the tool call ID
-         * - Second parameter: rawParams (Record<string, unknown>) - the actual parameters
-         * - Third parameter (optional): signal (AbortSignal) - for cancellation
-         */
-        async execute(_toolCallId, rawParams) {
-            const agentType = readStringParam(rawParams, 'agentType') || '';
-            const task = readStringParam(rawParams, 'task') || '';
-            const runAsync = readBooleanParam(rawParams, 'runInBackground') === true;
-            const availableInternalAgents = listAvailableAgents();
-            // Log summary at info level, full params at debug level
-            api.logger?.info?.(`[PD:AgentSpawn] toolCallId=${_toolCallId}, agentType=${agentType || 'MISSING'}, hasTask=${!!task}, taskLength=${task.length}, runInBackground=${runAsync}`);
-            api.logger?.debug?.(`[PD:AgentSpawn] Full rawParams: ${JSON.stringify(sanitizeParamsForLogging(rawParams))}`);
-            if (!agentType) {
-                api.logger?.warn?.(`[PD:AgentSpawn] Missing agentType, hasTask=${!!task}`);
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `❌ 缺少 agentType 参数。请按以下格式调用:
-
-pd_run_worker(
-  agentType="diagnostician",  // 必填: explorer, diagnostician, auditor, planner, implementer, reviewer, reporter
-  task="分析问题的根因"        // 必填: 任务描述
-)
-
-可用的智能体类型: ${availableInternalAgents.join(', ')}`
-                        }]
-                };
-            }
-            if (!task) {
-                api.logger?.warn?.(`[PD:AgentSpawn] Missing task for agentType=${agentType}`);
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `❌ 缺少 task 参数。请提供任务描述，例如:
-
-pd_run_worker(
-  agentType="${agentType || 'diagnostician'}",
-  task="分析 Pain xxx 的根因"
-)`
-                        }]
-                };
-            }
-            if (looksLikeSessionOrPeerCoordinationTask(task)) {
-                api.logger?.warn?.(`[PD:AgentSpawn] Rejected likely peer/session misuse for task: ${task}`);
-                return {
-                    content: [{
-                            type: 'text',
-                            text: buildInternalAgentUsageMessage(availableInternalAgents)
-                        }]
-                };
-            }
-            if (!availableInternalAgents.includes(agentType)) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `❌ 未知的智能体类型: "${agentType}"
-
-可用的智能体类型: ${availableInternalAgents.join(', ')}
-
-示例: pd_run_worker(agentType="diagnostician", task="分析问题根因")`
-                        }]
-                };
-            }
-            // Load agent definition
-            const agentDef = loadAgentDefinition(agentType);
-            if (!agentDef) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `❌ 无法加载智能体定义: ${agentType}`
-                        }]
-                };
-            }
-            // Check subagent runtime availability.
-            // api.runtime.subagent is always a Proxy object (truthy), even in embedded mode.
-            // Use the shared probe utility to detect which mode we're in.
-            const subagentRuntime = api.runtime?.subagent;
-            if (!isSubagentRuntimeAvailable(subagentRuntime)) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `❌ Subagent runtime 不可用。\n\n当前运行在 embedded 模式（openclaw agent CLI），该模式不支持派生子智能体。\n\n请通过 Gateway 模式运行（openclaw gateway），然后再调用 pd_run_worker。`
-                        }]
-                };
-            }
-            // Build session key
-            const sessionKey = `agent:${agentType}:${randomUUID()}`;
-            // Build system prompt
-            const extraSystemPrompt = buildSubagentSystemPrompt(agentDef, task);
-            const startTime = Date.now();
-            try {
-                // Run subagent
-                await subagentRuntime.run({
-                    sessionKey,
-                    message: task,
-                    extraSystemPrompt,
-                    lane: 'subagent',
-                    deliver: false, // Critical: don't send directly to external channels
-                    idempotencyKey: randomUUID(),
-                });
-                if (agentType === 'diagnostician') {
-                    await registerDiagnosticianRun(api, task, sessionKey);
-                }
-                if (runAsync) {
-                    const duration = Date.now() - startTime;
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: `✅ 已在后台启动 **${agentDef.name}** (${(duration / 1000).toFixed(1)}s)。它不会阻塞当前对话。`
-                            }]
-                    };
-                }
-                // Wait for completion (with configurable timeout to prevent indefinite block)
-                const timeoutMs = api.config?.get?.('intervals.task_timeout_ms') || (30 * 60 * 1000);
-                const result = await subagentRuntime.waitForRun({
-                    runId: sessionKey,
-                    timeoutMs,
-                });
-                const duration = Date.now() - startTime;
-                // Handle timeout
-                if (result.status === 'timeout') {
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: `⚠️ 智能体 **${agentDef.name}** 执行超时 (${(duration / 1000).toFixed(1)}s)。
-
-建议：
-- 简化任务描述
-- 分解为多个子任务
-- 检查任务是否需要更多上下文`
-                            }]
-                    };
-                }
-                // Handle error
-                if (result.status === 'error') {
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: `❌ 智能体 **${agentDef.name}** 执行失败: ${result.error || '未知错误'}`
-                            }]
-                    };
-                }
-                // Get results
-                const messages = await subagentRuntime.getSessionMessages({ sessionKey });
-                const output = extractAssistantText(messages);
-                if (!output || output.trim() === '') {
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: `⚠️ 智能体 **${agentDef.name}** 执行完成，但没有返回输出。`
-                            }]
-                    };
-                }
-                // Return formatted result
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `✅ **${agentDef.name}** 执行完成 (${(duration / 1000).toFixed(1)}s)
-
----
-
-${output}`
-                        }]
-                };
-            }
-            catch (err) {
-                const errorMsg = err instanceof Error ? err.message : String(err);
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `❌ 智能体 **${agentDef.name}** 执行异常: ${errorMsg}`
-                        }]
-                };
-            }
-            finally {
-                // Cleanup session (P1 fix: log failures instead of silent swallow)
-                if (!runAsync) {
-                    try {
-                        await subagentRuntime.deleteSession({ sessionKey });
-                    }
-                    catch (cleanupErr) {
-                        const cleanupErrMsg = cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr);
-                        api.logger?.error?.(`[PD:AgentSpawn] Failed to cleanup session ${sessionKey}: ${cleanupErrMsg}`);
-                    }
-                }
-            }
-        },
-    };
-}
-// Legacy export for backward compatibility with internal code
-// This is the "unconfigured" tool that needs to be created via createAgentSpawnTool()
-export const agentSpawnTool = {
-    name: 'pd_run_worker',
-    description: `启动指定类型的子智能体执行任务。
-
-可用的智能体类型:
-- explorer: 快速收集证据（文件、日志、复现步骤）
-- diagnostician: 根因分析（verb/adjective + 5Whys）
-- auditor: 演演审计（axiom/system/via-negativa）
-- planner: 制定电影剧本计划
-- implementer: 按计划执行代码修改
-- reviewer: 代码审查（正确性、安全性、可维护性）
-- reporter: 最终汇报（技术细节转管理报告）
-
-示例调用: pd_run_worker(agentType="diagnostician", task="分析 Pain 7386ccfb 的根因")`,
-    parameters: Type.Object({
-        agentType: Type.String({
-            description: '【必填】智能体类型，必须是以下之一: explorer, diagnostician, auditor, planner, implementer, reviewer, reporter',
-        }),
-        task: Type.String({
-            description: '【必填】任务描述，告诉智能体要做什么',
-        }),
-        runInBackground: Type.Optional(Type.Boolean({
-            description: '【可选】是否后台运行。true=立即返回不等待结果，false=等待执行完成。默认 false',
-        })),
-    }),
-    // This execute method throws to prevent accidental usage of the unconfigured tool
-    execute: () => {
-        throw new Error('agentSpawnTool is a metadata-only export. ' +
-            'Use createAgentSpawnTool(api) to get an executable instance.');
-    },
-};
-/**
- * Batch spawn multiple agents in sequence
- * Useful for evolution workflow
- */
-export async function spawnAgentSequence(agents, api, onProgress) {
-    const results = new Map();
-    const tool = createAgentSpawnTool(api);
-    for (const { type, task } of agents) {
-        const toolCallId = `spawn-sequence-${type}-${randomUUID()}`;
-        const result = await tool.execute(toolCallId, { agentType: type, task });
-        const text = result.content[0]?.text || '';
-        results.set(type, text);
-        onProgress?.(type, text);
-    }
-    return results;
-}