@lobehub/lobehub 2.0.0-next.327 → 2.0.0-next.328

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 # Changelog
 
+## [Version 2.0.0-next.328](https://github.com/lobehub/lobe-chat/compare/v2.0.0-next.327...v2.0.0-next.328)
+
+<sup>Released on **2026-01-20**</sup>
+
+#### ✨ Features
+
+- **misc**: Support client tasks mode.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's improved
+
+- **misc**: Support client tasks mode, closes [#11666](https://github.com/lobehub/lobe-chat/issues/11666) ([98cf57b](https://github.com/lobehub/lobe-chat/commit/98cf57b))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
 ## [Version 2.0.0-next.327](https://github.com/lobehub/lobe-chat/compare/v2.0.0-next.326...v2.0.0-next.327)
 
 <sup>Released on **2026-01-20**</sup>

package/changelog/v1.json

@@ -1,4 +1,13 @@
 [
+  {
+    "children": {
+      "features": [
+        "Support client tasks mode."
+      ]
+    },
+    "date": "2026-01-20",
+    "version": "2.0.0-next.328"
+  },
   {
     "children": {},
     "date": "2026-01-20",

package/locales/en-US/chat.json

@@ -204,6 +204,7 @@
   "noSelectedAgents": "No members selected yet",
   "openInNewWindow": "Open in New Window",
   "operation.execAgentRuntime": "Preparing response",
+  "operation.execClientTask": "Executing task",
   "operation.sendMessage": "Sending message",
   "owner": "Group owner",
   "pageCopilot.title": "Page Agent",
@@ -322,13 +323,17 @@
   "tab.profile": "Agent Profile",
   "tab.search": "Search",
   "task.activity.calling": "Calling Skill...",
+  "task.activity.clientExecuting": "Executing locally...",
   "task.activity.generating": "Generating response...",
   "task.activity.gotResult": "Tool result received",
   "task.activity.toolCalling": "Calling {{toolName}}...",
   "task.activity.toolResult": "{{toolName}} result received",
   "task.batchTasks": "{{count}} Batch Subtasks",
+  "task.instruction": "Task Instruction",
+  "task.intermediateSteps": "{{count}} intermediate steps",
+  "task.metrics.duration": "(took {{duration}})",
   "task.metrics.stepsShort": "steps",
-  "task.metrics.toolCallsShort": "tool uses",
+  "task.metrics.toolCallsShort": "skill uses",
   "task.status.cancelled": "Task Cancelled",
   "task.status.failed": "Task Failed",
   "task.status.initializing": "Initializing task...",

package/locales/zh-CN/chat.json

@@ -204,6 +204,7 @@
   "noSelectedAgents": "还未选择成员",
   "openInNewWindow": "在新窗口打开",
   "operation.execAgentRuntime": "准备响应中",
+  "operation.execClientTask": "执行任务中",
   "operation.sendMessage": "消息发送中",
   "owner": "群主",
   "pageCopilot.title": "文稿助理",
@@ -322,11 +323,15 @@
   "tab.profile": "助理档案",
   "tab.search": "搜索",
   "task.activity.calling": "正在调用技能…",
+  "task.activity.clientExecuting": "本地执行中…",
   "task.activity.generating": "正在生成回复…",
   "task.activity.gotResult": "已获取技能结果",
   "task.activity.toolCalling": "正在调用 {{toolName}}…",
   "task.activity.toolResult": "已获取 {{toolName}} 结果",
   "task.batchTasks": "{{count}} 个批量子任务",
+  "task.instruction": "任务说明",
+  "task.intermediateSteps": "{{count}} 个中间步骤",
+  "task.metrics.duration": "（用时 {{duration}}）",
   "task.metrics.stepsShort": "步",
   "task.metrics.toolCallsShort": "次技能调用",
   "task.status.cancelled": "任务已取消",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lobehub/lobehub",
-  "version": "2.0.0-next.327",
+  "version": "2.0.0-next.328",
   "description": "LobeHub - an open-source,comprehensive AI Agent framework that supports speech synthesis, multimodal, and extensible Function Call plugin system. Supports one-click free deployment of your private ChatGPT/LLM web application.",
   "keywords": [
     "framework",

package/packages/agent-runtime/src/agents/GeneralChatAgent.ts

@@ -359,6 +359,30 @@ export class GeneralChatAgent implements Agent {
               type: 'exec_tasks',
             };
           }
+
+          // GTD client-side async task (single, desktop only)
+          if (stateType === 'execClientTask') {
+            const { parentMessageId: execParentId, task } = data.state as {
+              parentMessageId: string;
+              task: any;
+            };
+            return {
+              payload: { parentMessageId: execParentId, task },
+              type: 'exec_client_task',
+            };
+          }
+
+          // GTD client-side async tasks (multiple, desktop only)
+          if (stateType === 'execClientTasks') {
+            const { parentMessageId: execParentId, tasks } = data.state as {
+              parentMessageId: string;
+              tasks: any[];
+            };
+            return {
+              payload: { parentMessageId: execParentId, tasks },
+              type: 'exec_client_tasks',
+            };
+          }
         }
 
         // Check if there are still pending tool messages waiting for approval

package/packages/agent-runtime/src/agents/__tests__/GeneralChatAgent.test.ts

@@ -368,6 +368,216 @@ describe('GeneralChatAgent', () => {
   });
 
   describe('tool_result phase', () => {
+    describe('GTD async tasks', () => {
+      it('should return exec_task for single async task (execTask)', async () => {
+        const agent = new GeneralChatAgent({
+          agentConfig: { maxSteps: 100 },
+          operationId: 'test-session',
+          modelRuntimeConfig: mockModelRuntimeConfig,
+        });
+
+        const state = createMockState();
+        const context = createMockContext('tool_result', {
+          parentMessageId: 'tool-msg-1',
+          stop: true,
+          data: {
+            state: {
+              type: 'execTask',
+              parentMessageId: 'exec-parent-msg',
+              task: { instruction: 'Do something async', timeout: 30000 },
+            },
+          },
+        });
+
+        const result = await agent.runner(context, state);
+
+        expect(result).toEqual({
+          type: 'exec_task',
+          payload: {
+            parentMessageId: 'exec-parent-msg',
+            task: { instruction: 'Do something async', timeout: 30000 },
+          },
+        });
+      });
+
+      it('should return exec_tasks for multiple async tasks (execTasks)', async () => {
+        const agent = new GeneralChatAgent({
+          agentConfig: { maxSteps: 100 },
+          operationId: 'test-session',
+          modelRuntimeConfig: mockModelRuntimeConfig,
+        });
+
+        const state = createMockState();
+        const tasks = [
+          { instruction: 'Task 1', timeout: 30000 },
+          { instruction: 'Task 2', timeout: 30000 },
+        ];
+        const context = createMockContext('tool_result', {
+          parentMessageId: 'tool-msg-1',
+          stop: true,
+          data: {
+            state: {
+              type: 'execTasks',
+              parentMessageId: 'exec-parent-msg',
+              tasks,
+            },
+          },
+        });
+
+        const result = await agent.runner(context, state);
+
+        expect(result).toEqual({
+          type: 'exec_tasks',
+          payload: {
+            parentMessageId: 'exec-parent-msg',
+            tasks,
+          },
+        });
+      });
+
+      it('should return exec_client_task for single client-side async task (execClientTask)', async () => {
+        const agent = new GeneralChatAgent({
+          agentConfig: { maxSteps: 100 },
+          operationId: 'test-session',
+          modelRuntimeConfig: mockModelRuntimeConfig,
+        });
+
+        const state = createMockState();
+        const context = createMockContext('tool_result', {
+          parentMessageId: 'tool-msg-1',
+          stop: true,
+          data: {
+            state: {
+              type: 'execClientTask',
+              parentMessageId: 'exec-parent-msg',
+              task: { type: 'localFile', path: '/path/to/file' },
+            },
+          },
+        });
+
+        const result = await agent.runner(context, state);
+
+        expect(result).toEqual({
+          type: 'exec_client_task',
+          payload: {
+            parentMessageId: 'exec-parent-msg',
+            task: { type: 'localFile', path: '/path/to/file' },
+          },
+        });
+      });
+
+      it('should return exec_client_tasks for multiple client-side async tasks (execClientTasks)', async () => {
+        const agent = new GeneralChatAgent({
+          agentConfig: { maxSteps: 100 },
+          operationId: 'test-session',
+          modelRuntimeConfig: mockModelRuntimeConfig,
+        });
+
+        const state = createMockState();
+        const tasks = [
+          { type: 'localFile', path: '/path/to/file1' },
+          { type: 'localFile', path: '/path/to/file2' },
+        ];
+        const context = createMockContext('tool_result', {
+          parentMessageId: 'tool-msg-1',
+          stop: true,
+          data: {
+            state: {
+              type: 'execClientTasks',
+              parentMessageId: 'exec-parent-msg',
+              tasks,
+            },
+          },
+        });
+
+        const result = await agent.runner(context, state);
+
+        expect(result).toEqual({
+          type: 'exec_client_tasks',
+          payload: {
+            parentMessageId: 'exec-parent-msg',
+            tasks,
+          },
+        });
+      });
+
+      it('should not trigger exec_task when stop is false', async () => {
+        const agent = new GeneralChatAgent({
+          agentConfig: { maxSteps: 100 },
+          operationId: 'test-session',
+          modelRuntimeConfig: mockModelRuntimeConfig,
+        });
+
+        const state = createMockState({
+          messages: [
+            { role: 'user', content: 'Hello' },
+            { role: 'assistant', content: '' },
+            { role: 'tool', content: 'Result', tool_call_id: 'call-1' },
+          ] as any,
+        });
+        const context = createMockContext('tool_result', {
+          parentMessageId: 'tool-msg-1',
+          stop: false, // stop is false, should not trigger exec_task
+          data: {
+            state: {
+              type: 'execTask',
+              parentMessageId: 'exec-parent-msg',
+              task: { instruction: 'Do something async' },
+            },
+          },
+        });
+
+        const result = await agent.runner(context, state);
+
+        // Should return call_llm instead of exec_task
+        expect(result).toEqual({
+          type: 'call_llm',
+          payload: {
+            messages: state.messages,
+            model: 'gpt-4o-mini',
+            parentMessageId: 'tool-msg-1',
+            provider: 'openai',
+            tools: undefined,
+          },
+        });
+      });
+
+      it('should not trigger exec_task when data.state is undefined', async () => {
+        const agent = new GeneralChatAgent({
+          agentConfig: { maxSteps: 100 },
+          operationId: 'test-session',
+          modelRuntimeConfig: mockModelRuntimeConfig,
+        });
+
+        const state = createMockState({
+          messages: [
+            { role: 'user', content: 'Hello' },
+            { role: 'assistant', content: '' },
+            { role: 'tool', content: 'Result', tool_call_id: 'call-1' },
+          ] as any,
+        });
+        const context = createMockContext('tool_result', {
+          parentMessageId: 'tool-msg-1',
+          stop: true,
+          data: {}, // No state property
+        });
+
+        const result = await agent.runner(context, state);
+
+        // Should return call_llm instead of exec_task
+        expect(result).toEqual({
+          type: 'call_llm',
+          payload: {
+            messages: state.messages,
+            model: 'gpt-4o-mini',
+            parentMessageId: 'tool-msg-1',
+            provider: 'openai',
+            tools: undefined,
+          },
+        });
+      });
+    });
+
     it('should return call_llm when no pending tools', async () => {
       const agent = new GeneralChatAgent({
         agentConfig: { maxSteps: 100 },

package/packages/agent-runtime/src/types/instruction.ts

@@ -236,12 +236,26 @@ export interface ExecTaskItem {
   inheritMessages?: boolean;
   /** Detailed instruction/prompt for the task execution */
   instruction: string;
+  /**
+   * Whether to execute the task on the client side (desktop only).
+   * When true and running on desktop, the task will be executed locally
+   * with access to local tools (file system, shell commands, etc.).
+   *
+   * IMPORTANT: This MUST be set to true when the task requires:
+   * - Reading/writing local files via `local-system` tool
+   * - Executing shell commands
+   * - Any other desktop-only local tool operations
+   *
+   * If not specified or false, the task runs on the server (default behavior).
+   * On non-desktop platforms (web), this flag is ignored and tasks always run on server.
+   */
+  runInClient?: boolean;
   /** Timeout in milliseconds (optional, default 30 minutes) */
   timeout?: number;
 }
 
 /**
- * Instruction to execute a single async task
+ * Instruction to execute a single async task (server-side)
  */
 export interface AgentInstructionExecTask {
   payload: {
@@ -254,7 +268,7 @@ export interface AgentInstructionExecTask {
 }
 
 /**
- * Instruction to execute multiple async tasks in parallel
+ * Instruction to execute multiple async tasks in parallel (server-side)
  */
 export interface AgentInstructionExecTasks {
   payload: {
@@ -266,6 +280,34 @@ export interface AgentInstructionExecTasks {
   type: 'exec_tasks';
 }
 
+/**
+ * Instruction to execute a single async task on the client (desktop only)
+ * Used when task requires local tools like file system or shell commands
+ */
+export interface AgentInstructionExecClientTask {
+  payload: {
+    /** Parent message ID (tool message that triggered the task) */
+    parentMessageId: string;
+    /** Task to execute */
+    task: ExecTaskItem;
+  };
+  type: 'exec_client_task';
+}
+
+/**
+ * Instruction to execute multiple async tasks on the client in parallel (desktop only)
+ * Used when tasks require local tools like file system or shell commands
+ */
+export interface AgentInstructionExecClientTasks {
+  payload: {
+    /** Parent message ID (tool message that triggered the tasks) */
+    parentMessageId: string;
+    /** Array of tasks to execute */
+    tasks: ExecTaskItem[];
+  };
+  type: 'exec_client_tasks';
+}
+
 /**
  * Payload for task_result phase (single task)
  */
@@ -318,6 +360,8 @@ export type AgentInstruction =
   | AgentInstructionCallToolsBatch
   | AgentInstructionExecTask
   | AgentInstructionExecTasks
+  | AgentInstructionExecClientTask
+  | AgentInstructionExecClientTasks
   | AgentInstructionRequestHumanPrompt
   | AgentInstructionRequestHumanSelect
   | AgentInstructionRequestHumanApprove

package/packages/builtin-tool-gtd/src/const.ts

@@ -0,0 +1 @@
+export const isDesktop = process.env.NEXT_PUBLIC_IS_DESKTOP_APP === '1';

package/packages/builtin-tool-gtd/src/executor/index.ts

@@ -407,18 +407,20 @@ class GTDExecutor extends BaseExecutor<typeof GTDApiNameEnum> {
    * Execute a single async task
    *
    * This method triggers async task execution by returning a special state.
-   * The AgentRuntime's executor will recognize this state and trigger the exec_task instruction.
+   * The AgentRuntime's executor will recognize this state and trigger the appropriate instruction.
    *
    * Flow:
-   * 1. GTD tool returns stop: true with state.type = 'execTask'
-   * 2. AgentRuntime executor recognizes the state and triggers exec_task instruction
-   * 3. exec_task executor creates task message and polls for completion
+   * 1. GTD tool returns stop: true with state.type = 'execTask' or 'execClientTask'
+   * 2. AgentRuntime executor recognizes the state and triggers exec_task or exec_client_task instruction
+   * 3. The executor creates task message and handles execution
+   *
+   * @param params.runInClient - If true, returns 'execClientTask' state for client-side execution
    */
   execTask = async (
     params: ExecTaskParams,
     ctx: BuiltinToolContext,
   ): Promise<BuiltinToolResult> => {
-    const { description, instruction, inheritMessages, timeout } = params;
+    const { description, instruction, inheritMessages, timeout, runInClient } = params;
 
     if (!description || !instruction) {
       return {
@@ -427,19 +429,25 @@ class GTDExecutor extends BaseExecutor<typeof GTDApiNameEnum> {
       };
     }
 
+    const task = {
+      description,
+      inheritMessages,
+      instruction,
+      runInClient,
+      timeout,
+    };
+
+    // Determine state type based on runInClient
+    // If runInClient is true, return 'execClientTask' to trigger client-side executor
+    const stateType = runInClient ? 'execClientTask' : 'execTask';
+
     // Return stop: true with special state that AgentRuntime will recognize
-    // The exec_task executor will be triggered by the runtime when it sees this state
     return {
-      content: `🚀 Triggered async task for execution:\n- ${description}`,
+      content: `🚀 Triggered async task for ${runInClient ? 'client-side' : ''} execution:\n- ${description}`,
       state: {
         parentMessageId: ctx.messageId,
-        task: {
-          description,
-          inheritMessages,
-          instruction,
-          timeout,
-        },
-        type: 'execTask',
+        task,
+        type: stateType,
       },
       stop: true,
       success: true,
@@ -450,12 +458,15 @@ class GTDExecutor extends BaseExecutor<typeof GTDApiNameEnum> {
    * Execute one or more async tasks
    *
    * This method triggers async task execution by returning a special state.
-   * The AgentRuntime's executor will recognize this state and trigger the exec_tasks instruction.
+   * The AgentRuntime's executor will recognize this state and trigger the appropriate instruction.
    *
    * Flow:
-   * 1. GTD tool returns stop: true with state.type = 'execTasks'
-   * 2. AgentRuntime executor recognizes the state and triggers exec_tasks instruction
-   * 3. exec_tasks executor creates task messages and polls for completion
+   * 1. GTD tool returns stop: true with state.type = 'execTasks' or 'execClientTasks'
+   * 2. AgentRuntime executor recognizes the state and triggers exec_tasks or exec_client_tasks instruction
+   * 3. The executor creates task messages and handles execution
+   *
+   * Note: If any task has runInClient=true, all tasks will be routed to 'execClientTasks'.
+   * This is because client-side execution is the "special" case requiring local tool access.
    */
   execTasks = async (
     params: ExecTasksParams,
@@ -473,14 +484,20 @@ class GTDExecutor extends BaseExecutor<typeof GTDApiNameEnum> {
     const taskCount = tasks.length;
     const taskList = tasks.map((t, i) => `${i + 1}. ${t.description}`).join('\n');
 
+    // Check if any task requires client-side execution
+    const hasClientTasks = tasks.some((t) => t.runInClient);
+
+    // Determine state type: if any task needs client-side, route all to client executor
+    const stateType = hasClientTasks ? 'execClientTasks' : 'execTasks';
+    const executionMode = hasClientTasks ? 'client-side' : '';
+
     // Return stop: true with special state that AgentRuntime will recognize
-    // The exec_tasks executor will be triggered by the runtime when it sees this state
     return {
-      content: `🚀 Triggered ${taskCount} async task${taskCount > 1 ? 's' : ''} for execution:\n${taskList}`,
+      content: `🚀 Triggered ${taskCount} async task${taskCount > 1 ? 's' : ''} for ${executionMode} execution:\n${taskList}`,
       state: {
         parentMessageId: ctx.messageId,
         tasks,
-        type: 'execTasks',
+        type: stateType,
       },
       stop: true,
       success: true,

package/packages/builtin-tool-gtd/src/manifest.ts

@@ -1,5 +1,6 @@
 import type { BuiltinToolManifest } from '@lobechat/types';
 
+import { isDesktop } from './const';
 import { systemPrompt } from './systemRole';
 import { GTDApiName } from './types';
 
@@ -171,6 +172,13 @@ export const GTDManifest: BuiltinToolManifest = {
               'Whether to inherit context messages from the parent conversation. Default is false.',
             type: 'boolean',
           },
+          ...(isDesktop && {
+            runInClient: {
+              description:
+                'Whether to run on the desktop client (for local file/shell access). MUST be true when task requires local-system tools. Default is false (server execution).',
+              type: 'boolean',
+            },
+          }),
           timeout: {
             description: 'Optional timeout in milliseconds. Default is 30 minutes.',
             type: 'number',
@@ -203,6 +211,13 @@ export const GTDManifest: BuiltinToolManifest = {
                     'Whether to inherit context messages from the parent conversation. Default is false.',
                   type: 'boolean',
                 },
+                ...(isDesktop && {
+                  runInClient: {
+                    description:
+                      'Whether to run on the desktop client (for local file/shell access). MUST be true when task requires local-system tools. Default is false (server execution).',
+                    type: 'boolean',
+                  },
+                }),
                 timeout: {
                   description: 'Optional timeout in milliseconds. Default is 30 minutes.',
                   type: 'number',

package/packages/builtin-tool-gtd/src/systemRole.ts

@@ -1,3 +1,35 @@
+import { isDesktop } from './const';
+
+const runInClientSection = `
+<run_in_client>
+**IMPORTANT: When to use \`runInClient: true\` for async tasks**
+
+The \`runInClient\` parameter controls WHERE the async task executes:
+- \`runInClient: false\` (default): Task runs on the **server** - suitable for web searches, API calls, general research
+- \`runInClient: true\`: Task runs on the **desktop client** - required for local system access
+
+**MUST set \`runInClient: true\` when the task involves:**
+- Reading or writing local files (via \`local-system\` tool)
+- Executing shell commands on the user's machine
+- Accessing local directories or file system
+- Any operation that requires desktop-only local tools
+
+**Keep \`runInClient: false\` (or omit) when:**
+- Task only needs web searches or API calls
+- Task processes data that doesn't require local file access
+- Task can be fully completed with server-side capabilities
+
+**Note:** \`runInClient\` only has effect on the **desktop app**. On web platform, tasks always run on the server regardless of this setting.
+
+**Examples:**
+- "Research Python best practices" → \`runInClient: false\` (web search only)
+- "Organize files in my Downloads folder" → \`runInClient: true\` (local file access required)
+- "Read the project README and summarize it" → \`runInClient: true\` (local file read required)
+- "Find trending tech news" → \`runInClient: false\` (web search only)
+- "Create a new directory structure for my project" → \`runInClient: true\` (local shell/file required)
+</run_in_client>
+`;
+
 export const systemPrompt = `You have GTD (Getting Things Done) tools to help manage plans, todos and tasks effectively. These tools support three levels of task management:
 
 - **Plan**: A high-level strategic document describing goals, context, and overall direction. Plans do NOT contain actionable steps - they define the "what" and "why". **Plans should be stable once created** - they represent the overarching objective that rarely changes.
@@ -85,7 +117,7 @@ Use \`execTask\` for a single task, \`execTasks\` for multiple parallel tasks.
 - User asks a factual question you know → Just answer directly
 - User wants multiple independent analyses → execTasks (parallel execution)
 </when_to_use>
-
+${isDesktop ? runInClientSection : ''}
 <best_practices>
 - **Plan first, then todos**: Always start with a plan unless explicitly told otherwise
 - **Separate concerns**: Plans describe goals; Todos list actions