principles-disciple 1.6.0 → 1.7.1

package/dist/tools/agent-spawn.js

@@ -49,110 +49,359 @@ function buildSubagentSystemPrompt(agentDef, _task) {
     // 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.';
+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 session.',
+        'Use `sessions_list` to inspect running sessions.',
+        'Use `sessions_send` to talk to another existing session.',
+    ].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',
+        '同级智能体',
+        '另一个智能体',
+        '其他智能体',
+        '另一个会话',
+        '其他会话',
+        '跨会话',
+        '给另一个会话发消息',
+    ];
+    return explicitMarkers.some((marker) => normalized.includes(marker));
+}
 /**
- * Agent Spawn Tool definition
+ * Sanitize params for debug logging (remove sensitive values)
  */
-export const agentSpawnTool = {
-    name: 'pd_spawn_agent',
-    description: `启动指定类型的子智能体执行任务。
+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）
+- auditor: 演演审计（axiom/system/via-negativa）
 - planner: 制定电影剧本计划
 - implementer: 按计划执行代码修改
 - reviewer: 代码审查（正确性、安全性、可维护性）
-- reporter: 最终汇报（技术细节转管理报告）`,
-    parameters: Type.Object({
-        agentType: Type.String({
-            description: '智能体类型: explorer, diagnostician, auditor, planner, implementer, reviewer, reporter',
-        }),
-        task: Type.String({
-            description: '任务描述，详细说明子智能体需要完成的工作',
+- 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
-     */
-    async execute(params, api, _workspaceDir) {
-        const { agentType, task } = params;
-        // 1. Validate agent type
-        const availableAgents = listAvailableAgents();
-        if (!availableAgents.includes(agentType)) {
-            return `❌ 未找到智能体定义: "${agentType}"。
+        /**
+         * 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 参数。请按以下格式调用:
 
-可用的智能体: ${availableAgents.join(', ')}`;
-        }
-        // 2. Load agent definition
-        const agentDef = loadAgentDefinition(agentType);
-        if (!agentDef) {
-            return `❌ 无法加载智能体定义: ${agentType}`;
-        }
-        // 3. Check subagent runtime availability
-        const subagentRuntime = api.runtime?.subagent;
-        if (!subagentRuntime) {
-            return `❌ Subagent runtime 不可用。请确保 OpenClaw Gateway 正在运行。`;
-        }
-        // 4. Build session key
-        const sessionKey = `agent:${agentType}:${randomUUID()}`;
-        // 5. Build system prompt
-        const extraSystemPrompt = buildSubagentSystemPrompt(agentDef, task);
-        const startTime = Date.now();
-        try {
-            // 6. Run subagent
-            await subagentRuntime.run({
-                sessionKey,
-                message: task,
-                extraSystemPrompt,
-                lane: 'subagent',
-                deliver: false, // Critical: don't send directly to external channels
-                idempotencyKey: randomUUID(),
-            });
-            // 7. Wait for completion
-            const result = await subagentRuntime.waitForRun({
-                runId: sessionKey,
-            });
-            const duration = Date.now() - startTime;
-            // 8. Handle timeout
-            if (result.status === 'timeout') {
-                return `⚠️ 智能体 **${agentDef.name}** 执行超时 (${(duration / 1000).toFixed(1)}s)。
+pd_run_worker(
+  agentType="diagnostician",  // 必填: explorer, diagnostician, auditor, planner, implementer, reviewer, reporter
+  task="分析问题的根因"        // 必填: 任务描述
+)
 
-建议：
-- 简化任务描述
-- 分解为多个子任务
-- 检查任务是否需要更多上下文`;
+可用的智能体类型: ${availableInternalAgents.join(', ')}`
+                        }]
+                };
             }
-            // 9. Handle error
-            if (result.status === 'error') {
-                return `❌ 智能体 **${agentDef.name}** 执行失败: ${result.error || '未知错误'}`;
+            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 的根因"
+)`
+                        }]
+                };
             }
-            // 10. Get results
-            const messages = await subagentRuntime.getSessionMessages({ sessionKey });
-            const output = extractAssistantText(messages);
-            if (!output || output.trim() === '') {
-                return `⚠️ 智能体 **${agentDef.name}** 执行完成，但没有返回输出。`;
+            if (looksLikeSessionOrPeerCoordinationTask(task)) {
+                api.logger?.warn?.(`[PD:AgentSpawn] Rejected likely peer/session misuse for task: ${task}`);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: buildInternalAgentUsageMessage(availableInternalAgents)
+                        }]
+                };
             }
-            // 11. Return formatted result
-            return `✅ **${agentDef.name}** 执行完成 (${(duration / 1000).toFixed(1)}s)
+            if (!availableInternalAgents.includes(agentType)) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `❌ 未知的智能体类型: "${agentType}"
 
----
+可用的智能体类型: ${availableInternalAgents.join(', ')}
 
-${output}`;
-        }
-        catch (err) {
-            const errorMsg = err instanceof Error ? err.message : String(err);
-            return `❌ 智能体 **${agentDef.name}** 执行异常: ${errorMsg}`;
-        }
-        finally {
-            // 12. Cleanup session
+示例: 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
+            const subagentRuntime = api.runtime?.subagent;
+            if (!subagentRuntime) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `❌ Subagent runtime 不可用。请确保 OpenClaw Gateway 正在运行。`
+                        }]
+                };
+            }
+            // Build session key
+            const sessionKey = `agent:${agentType}:${randomUUID()}`;
+            // Build system prompt
+            const extraSystemPrompt = buildSubagentSystemPrompt(agentDef, task);
+            const startTime = Date.now();
             try {
-                await subagentRuntime.deleteSession({ sessionKey });
+                // Run subagent
+                await subagentRuntime.run({
+                    sessionKey,
+                    message: task,
+                    extraSystemPrompt,
+                    lane: 'subagent',
+                    deliver: false, // Critical: don't send directly to external channels
+                    idempotencyKey: randomUUID(),
+                });
+                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 {
-                // Ignore cleanup errors
+            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.');
     },
 };
 /**
@@ -161,10 +410,13 @@ ${output}`;
  */
 export async function spawnAgentSequence(agents, api, onProgress) {
     const results = new Map();
+    const tool = createAgentSpawnTool(api);
     for (const { type, task } of agents) {
-        const result = await agentSpawnTool.execute({ agentType: type, task }, api);
-        results.set(type, result);
-        onProgress?.(type, result);
+        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;
 }

package/dist/tools/deep-reflect.d.ts

@@ -1,5 +1,11 @@
 import type { OpenClawPluginApi } from '../openclaw-sdk.js';
-export declare const deepReflectTool: {
+/**
+ * Create Deep Reflect 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 declare function createDeepReflectTool(api: OpenClawPluginApi): {
     name: string;
     description: string;
     parameters: import("@sinclair/typebox").TObject<{
@@ -9,11 +15,25 @@ export declare const deepReflectTool: {
     }>;
     /**
      * Tool execution logic
-     * @param workspaceDir Optional parameter for unit testing
+     *
+     * 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
      */
-    execute(params: {
-        context: string;
-        depth?: number;
-        model_id?: string;
-    }, api: OpenClawPluginApi, workspaceDir?: string): Promise<string>;
+    execute(_toolCallId: string, rawParams: Record<string, unknown>): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+};
+export declare const deepReflectTool: {
+    name: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        context: import("@sinclair/typebox").TString;
+        depth: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        model_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
 };