@yeaft/webchat-agent 0.1.1065 → 0.1.1067

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.1065",
+  "version": "0.1.1067",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/yeaft/conversation/persist.js

@@ -186,6 +186,9 @@ function serializeMessage(msg) {
   if (msg.model) fm.push(`model: ${msg.model}`);
   if (msg.turnNumber != null) fm.push(`turnNumber: ${msg.turnNumber}`);
   if (msg.toolCallId) fm.push(`toolCallId: ${msg.toolCallId}`);
+  if (msg.eventType) fm.push(`eventType: ${msg.eventType}`);
+  if (msg.taskId) fm.push(`taskId: ${msg.taskId}`);
+  if (msg.taskStatus) fm.push(`taskStatus: ${msg.taskStatus}`);
   if (msg.isError) fm.push(`isError: true`);
   // task-307: every message is stamped with a threadId so multi-thread
   // routing can filter/replay by thread without rescanning JSON blobs.
@@ -312,6 +315,9 @@ export function parseMessage(raw) {
       case 'model': msg.model = value; break;
       case 'turnNumber': msg.turnNumber = parseInt(value, 10); break;
       case 'toolCallId': msg.toolCallId = value; break;
+      case 'eventType': msg.eventType = value; break;
+      case 'taskId': msg.taskId = value; break;
+      case 'taskStatus': msg.taskStatus = value; break;
       case 'isError': msg.isError = value === 'true'; break;
       case 'tokens_est': msg.tokens_est = parseInt(value, 10); break;
       case 'threadId': msg.threadId = value; break;

package/yeaft/engine.js

@@ -387,6 +387,9 @@ export class Engine {
   /** @type {import('./tools/registry.js').ToolRegistry|null} */
   #toolRegistry;
 
+  /** @type {import('./tasks/manager.js').TaskManager|null} */
+  #taskManager;
+
   /** @type {import('./skills.js').SkillManager|null} */
   #skillManager;
 
@@ -501,7 +504,7 @@ export class Engine {
    *   toolStats?: import('./stats/tool-usage.js').ToolUsageStats,
    * }} params
    */
-  constructor({ adapter, trace, config, conversationStore, memoryIndex, amsRegistry, toolRegistry, skillManager, mcpManager, yeaftDir, toolStats = null, sessionId = null, vpId = null, chatId = null }) {
+  constructor({ adapter, trace, config, conversationStore, memoryIndex, amsRegistry, toolRegistry, skillManager, mcpManager, yeaftDir, toolStats = null, taskManager = null, sessionId = null, vpId = null, chatId = null }) {
     this.#adapter = adapter;
     this.#trace = trace;
     this.#config = config;
@@ -511,6 +514,7 @@ export class Engine {
     this.#memoryIndex = memoryIndex || null;
     this.#amsRegistry = amsRegistry || null;
     this.#toolRegistry = toolRegistry || null;
+    this.#taskManager = taskManager || null;
     this.#skillManager = skillManager || null;
     this.#mcpManager = mcpManager || null;
     this.#yeaftDir = yeaftDir || null;
@@ -870,7 +874,7 @@ export class Engine {
    * @param {object} [args.taskCtx] — legacy task-context sub-block (optional)
    * @returns {string}
    */
-  #buildSystemPrompt({ prompt, memoryInjection, vpPersona, activeScope, sessionAnnouncement, projectDoc, taskCtx } = {}) {
+  #buildSystemPrompt({ prompt, memoryInjection, vpPersona, activeScope, sessionAnnouncement, projectDoc, taskCtx, activeTasks } = {}) {
     // Get relevant skill content if SkillManager is wired
     let skillContent = '';
     if (this.#skillManager && prompt) {
@@ -893,6 +897,7 @@ export class Engine {
       projectDoc,
       runtimePlatform: getRuntimePlatformInfo(),
       taskCtx,
+      activeTasks,
       // Worker-shape harness is descriptive metadata for human inspection;
       // production prompts skip it to save tokens. Re-enable via env when
       // diagnosing prompt structure issues.
@@ -997,6 +1002,10 @@ export class Engine {
       conversationStore: this.#conversationStore,
       adapter: this.#adapter,
       config: this.#config,
+      taskManager: this.#taskManager,
+      sessionId: vpCtx?.sessionId || this.#sessionId || null,
+      threadId: vpCtx?.threadId || this.#currentThreadId || MAIN_THREAD_ID,
+      currentVpId: vpCtx?.senderVpId || this.#vpId || null,
       // task-704b: per-tool-result hard cap derives from this. Threaded
       // from the live model (resolveModel(currentModel)) every turn so
       // fallbackModel switches see the new window. Falls back to
@@ -1047,6 +1056,7 @@ export class Engine {
         parentVpId: vpCtx?.senderVpId || null,
         parentVpPersona: vpCtx?.vpPersona || null,
         parentSessionId: vpCtx?.sessionId || null,
+        parentThreadId: vpCtx?.threadId || this.#currentThreadId || MAIN_THREAD_ID,
         onEvent: this.#subAgentEventSink || null,
         language: this.#config?.language || 'en',
         // Forward the session-shared ToolUsageStats so sub-agent
@@ -1054,6 +1064,7 @@ export class Engine {
         // (~/.yeaft/stats/tool-usage.json) the parent engine writes
         // to. Null when the parent has no stats wired (e.g. tests).
         toolStats: this.#toolStats || null,
+        taskManager: this.#taskManager || null,
       },
     };
   }
@@ -1614,6 +1625,9 @@ export class Engine {
     };
 
     const projectDoc = this.#getProjectDocBlock(workDir);
+    const activeTasks = this.#taskManager
+      ? this.#taskManager.renderActiveTasksForPrompt(runtimeSessionId)
+      : '';
 
     const systemPrompt = this.#buildSystemPrompt({
       prompt,
@@ -1622,6 +1636,7 @@ export class Engine {
       activeScope,
       sessionAnnouncement,
       projectDoc,
+      activeTasks,
     });
 
     // ─── HARD INVARIANT: Compact ≠ Dream (read DESIGN-COMPACT-VS-DREAM.md) ─

package/yeaft/prompts.js

@@ -309,6 +309,7 @@ export function buildSystemPrompt({
   sessionAnnouncement = '',
   projectDoc = '',
   runtimePlatform,
+  activeTasks = '',
 } = {}) {
   // Normalize app locales like `zh-CN` to prompt dictionary/template keys.
   const effectiveLang = normalizePromptLanguage(language);
@@ -411,6 +412,9 @@ export function buildSystemPrompt({
   const activeScopeBlock = renderActiveScope(activeScope, lang);
   if (activeScopeBlock) parts.push(activeScopeBlock);
 
+  const activeTaskText = typeof activeTasks === 'string' ? activeTasks.trim() : '';
+  if (activeTaskText) parts.push(activeTaskText);
+
   const multiVpRoutingBlock = renderMultiVpRouting(activeScope, lang);
   if (multiVpRoutingBlock) parts.push(multiVpRoutingBlock);
 

package/yeaft/runtime-platform.js

@@ -51,6 +51,35 @@ export function resolveDefaultShell(opts = {}) {
   };
 }
 
+/**
+ * Build a platform-specific shell invocation for executing a command string.
+ * Kept in runtime-platform so tools and task runners share OS behavior without
+ * depending on each other.
+ *
+ * @param {string} command
+ * @param {{ runtimePlatform?: object }} opts
+ */
+export function buildShellInvocation(command, opts = {}) {
+  const runtimePlatform = opts.runtimePlatform || getRuntimePlatformInfo();
+  const shell = runtimePlatform.defaultShell
+    ? {
+        command: runtimePlatform.defaultShell,
+        argsPrefix: Array.isArray(runtimePlatform.shellArgsPrefix) ? runtimePlatform.shellArgsPrefix : null,
+        family: runtimePlatform.shellFamily,
+      }
+    : resolveDefaultShell({ platform: runtimePlatform.platform });
+
+  const argsPrefix = Array.isArray(shell.argsPrefix)
+    ? shell.argsPrefix
+    : resolveDefaultShell({ platform: runtimePlatform.platform }).argsPrefix;
+
+  return {
+    command: shell.command,
+    args: [...argsPrefix, command],
+    family: shell.family || runtimePlatform.shellFamily || 'posix',
+  };
+}
+
 /**
  * @param {{ platform?: string, env?: NodeJS.ProcessEnv }} [opts]
  */

package/yeaft/session.js

@@ -26,6 +26,7 @@ import { Engine } from './engine.js';
 import { Compactor } from './compact/compactor.js';
 import { resolveContextWindow } from './models.js';
 import { ToolUsageStats } from './stats/tool-usage.js';
+import { TaskManager } from './tasks/manager.js';
 // H2.f.5 removed the old user-facing thread pipeline/dispatcher. The base
 // session still exposes a single default Engine; PR #797 adds group VP thread
 // engines in web-bridge runtime state, keyed below the session layer.
@@ -399,6 +400,7 @@ export async function loadSession(options = {}) {
   }
 
   // ─── 8. Build tool registry ────────────────────────────
+  const taskManager = new TaskManager({ yeaftDir, conversationStore });
   const toolRegistry = createFullRegistry();
 
   // Register any extra tools from caller
@@ -456,6 +458,7 @@ export async function loadSession(options = {}) {
     mcpManager,
     yeaftDir,
     toolStats,
+    taskManager,
   });
 
   // ─── 9a-pre. Create per-group history Compactor ────────
@@ -608,6 +611,7 @@ export async function loadSession(options = {}) {
     status,
     amsRegistry,
     toolStats,
+    taskManager,
     shutdown,
     // task-325c: user-initiated abort API. Delegates to web-bridge which
     // owns the single AbortController. Lazy-imported to avoid a hard cycle

package/yeaft/sub-agent/runner.js

@@ -154,6 +154,7 @@ export function startSubAgent(agent, deps = {}) {
     mcpManager: deps.mcpManager || null,
     yeaftDir: deps.yeaftDir || null,
     toolStats: deps.toolStats || null,
+    taskManager: deps.taskManager || null,
   });
 
   agent.subEngine = subEngine;
@@ -164,6 +165,9 @@ export function startSubAgent(agent, deps = {}) {
   agent.parentThreadId = deps.parentThreadId || 'main';
   agent.outputLog = createOutputLog(agent.id, deps.subAgentLogDir);
   agent.outputFile = agent.outputLog.path;
+  if (agent.taskId && deps.taskManager && agent.parentSessionId) {
+    try { deps.taskManager.setTaskLogPath(agent.parentSessionId, agent.taskId, agent.outputFile); } catch { /* ignore */ }
+  }
   agent.outputLog.write({ type: 'sub_agent_spawned', agentId: agent.id, agentName: agent.name, mission: agent.mission || agent.task || '' });
 
   // Compose the system-prompt-overlay we want injected.
@@ -268,6 +272,9 @@ async function driveSubAgent(agent, subEngine, vpPersona, deps) {
   const emit = (evt) => {
     const wrapped = wrapEvt(evt);
     try { agent.outputLog?.write(wrapped); } catch { /* ignore log failures */ }
+    if (agent.taskId && deps.taskManager && agent.parentSessionId) {
+      try { deps.taskManager.refreshTaskLog(agent.parentSessionId, agent.taskId); } catch { /* ignore */ }
+    }
     if (onEvent) {
       try { onEvent(agent.id, wrapped); } catch { /* ignore listener errors */ }
     }
@@ -497,6 +504,17 @@ function finalizeTerminal(agent, status, { error, deps } = {}) {
     error: error || agent.error || null,
   };
   try { agent.outputLog?.write(evt); } catch { /* ignore */ }
+  if (agent.taskId && deps?.taskManager && agent.parentSessionId) {
+    const taskStatus = status === STATUS.COMPLETED ? 'succeeded'
+      : status === STATUS.CLOSED ? 'cancelled'
+        : 'failed';
+    try {
+      deps.taskManager.completeTask(agent.parentSessionId, agent.taskId, {
+        status: taskStatus,
+        error: error || agent.error || null,
+      });
+    } catch { /* ignore */ }
+  }
   if (deps && typeof deps.onEvent === 'function') {
     try { deps.onEvent(agent.id, evt); } catch { /* ignore */ }
   }

package/yeaft/tasks/manager.js

@@ -0,0 +1,327 @@
+/**
+ * manager.js — Session-scoped background task manager.
+ *
+ * First-class tasks cover shell background commands today and provide the
+ * shared model that sub-agents can attach to next.
+ */
+
+import { randomUUID } from 'crypto';
+import { TaskStore, TASK_STATUS, isTerminalTaskStatus } from './store.js';
+import { startShellProcess } from './shell-runner.js';
+import { getRuntimePlatformInfo } from '../runtime-platform.js';
+
+const LOG_PREVIEW_BYTES = 4096;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function makeTaskId() {
+  return `task_${Date.now().toString(36)}_${randomUUID().slice(0, 8)}`;
+}
+
+function publicSnapshot(task) {
+  if (!task) return null;
+  return {
+    id: task.id,
+    sessionId: task.sessionId,
+    ownerVpId: task.ownerVpId || null,
+    kind: task.kind,
+    title: task.title,
+    status: task.status,
+    createdAt: task.createdAt,
+    startedAt: task.startedAt,
+    updatedAt: task.updatedAt,
+    endedAt: task.endedAt || null,
+    runtime: task.runtime || {},
+    log: task.log || {},
+    result: task.result || {},
+    source: task.source || {},
+  };
+}
+
+function formatTaskMessage(kind, task, extra = {}) {
+  const lines = [];
+  const label = kind === 'started' ? 'Task started' : 'Task finished';
+  lines.push(`[${label}]`);
+  lines.push(`taskId: ${task.id}`);
+  lines.push(`kind: ${task.kind}`);
+  lines.push(`status: ${task.status}`);
+  lines.push(`ownerVpId: ${task.ownerVpId || 'unknown'}`);
+  lines.push(`title: ${task.title}`);
+  if (task.runtime?.command) lines.push(`command: ${task.runtime.command}`);
+  if (task.runtime?.cwd) lines.push(`cwd: ${task.runtime.cwd}`);
+  if (task.log?.path) lines.push(`log: ${task.log.path}`);
+  if (extra.exitCode != null) lines.push(`exitCode: ${extra.exitCode}`);
+  if (extra.signal) lines.push(`signal: ${extra.signal}`);
+  if (extra.summary) lines.push(`summary: ${extra.summary}`);
+  if (extra.logTail) {
+    lines.push('logTail:');
+    lines.push(extra.logTail.trimEnd());
+  }
+  return lines.join('\n');
+}
+
+export class TaskManager {
+  constructor({ yeaftDir, conversationStore = null, onEvent = null, runtimePlatform = null } = {}) {
+    if (!yeaftDir) throw new Error('TaskManager requires yeaftDir');
+    this.store = new TaskStore({ yeaftDir });
+    this.conversationStore = conversationStore;
+    this.onEvent = typeof onEvent === 'function' ? onEvent : null;
+    this.runtimePlatform = runtimePlatform || getRuntimePlatformInfo();
+    this.active = new Map();
+    this.processes = new Map();
+    this.#loadPersistedRunningTasks();
+  }
+
+  setEventSink(onEvent) {
+    this.onEvent = typeof onEvent === 'function' ? onEvent : null;
+  }
+
+  #key(sessionId, taskId) {
+    return `${sessionId || 'default'}::${taskId}`;
+  }
+
+  #emit(event, task, extra = {}) {
+    const payload = { type: 'yeaft_task_event', event, task: publicSnapshot(task), ...extra };
+    try { this.onEvent?.(payload); } catch { /* event sinks must not break tasks */ }
+  }
+
+  #persistLifecycleMessage(task, kind, extra = {}) {
+    if (!this.conversationStore || !task?.sessionId) return;
+    try {
+      this.conversationStore.append({
+        role: 'assistant',
+        content: formatTaskMessage(kind, task, extra),
+        sessionId: task.sessionId,
+        threadId: task.source?.threadId || 'main',
+        ...(task.ownerVpId ? { speakerVpId: task.ownerVpId } : {}),
+        eventType: 'task_lifecycle',
+        taskId: task.id,
+        taskStatus: task.status,
+      });
+    } catch {
+      // Conversation persistence must not kill the background process.
+    }
+  }
+
+  #loadPersistedRunningTasks() {
+    for (const task of this.store.loadActiveTasks()) {
+      const orphaned = {
+        ...task,
+        status: TASK_STATUS.ORPHANED,
+        updatedAt: nowIso(),
+        endedAt: nowIso(),
+        result: {
+          ...(task.result || {}),
+          error: 'Agent restarted while task was running; process control was lost.',
+        },
+      };
+      this.store.writeTask(orphaned);
+      this.store.appendEvent(orphaned.sessionId, { event: 'orphaned', taskId: orphaned.id });
+      this.#persistLifecycleMessage(orphaned, 'finished', { summary: orphaned.result.error });
+      this.#emit('completed', orphaned);
+    }
+  }
+
+  startTask({ sessionId, ownerVpId = null, kind = 'tool', title = '', runtime = {}, source = {}, logPath = null } = {}) {
+    const taskId = makeTaskId();
+    const resolvedSessionId = sessionId || 'default';
+    const task = {
+      id: taskId,
+      sessionId: resolvedSessionId,
+      ownerVpId,
+      kind,
+      title: title || kind,
+      status: TASK_STATUS.RUNNING,
+      createdAt: nowIso(),
+      startedAt: nowIso(),
+      updatedAt: nowIso(),
+      endedAt: null,
+      source,
+      runtime,
+      log: {
+        path: logPath || this.store.logPath(resolvedSessionId, taskId),
+        bytes: 0,
+        preview: '',
+      },
+      result: {},
+    };
+    this.store.writeTask(task);
+    this.store.appendEvent(task.sessionId, { event: 'started', taskId: task.id, kind: task.kind });
+    this.active.set(this.#key(task.sessionId, task.id), task);
+    this.#persistLifecycleMessage(task, 'started');
+    this.#emit('started', task);
+    return publicSnapshot(task);
+  }
+
+  completeTask(sessionId, taskId, opts = {}) {
+    return this.#completeTask(sessionId, taskId, opts);
+  }
+
+  startShellTask({ command, cwd, sessionId, ownerVpId = null, title = '', source = {}, runtimePlatform = null } = {}) {
+    if (!command || typeof command !== 'string') throw new Error('command is required');
+    const task = {
+      id: makeTaskId(),
+      sessionId: sessionId || 'default',
+      ownerVpId,
+      kind: 'shell',
+      title: title || command.slice(0, 120),
+      status: TASK_STATUS.RUNNING,
+      createdAt: nowIso(),
+      startedAt: nowIso(),
+      updatedAt: nowIso(),
+      endedAt: null,
+      source,
+      runtime: {
+        command,
+        cwd,
+        pid: null,
+        platform: (runtimePlatform || this.runtimePlatform)?.platform || process.platform,
+      },
+      log: {
+        path: this.store.logPath(sessionId || 'default', 'pending'),
+        bytes: 0,
+        preview: '',
+      },
+      result: {},
+    };
+    task.log.path = this.store.logPath(task.sessionId, task.id);
+
+    this.store.writeTask(task);
+    this.store.appendEvent(task.sessionId, { event: 'started', taskId: task.id, kind: task.kind });
+    this.active.set(this.#key(task.sessionId, task.id), task);
+    this.#persistLifecycleMessage(task, 'started');
+    this.#emit('started', task);
+
+    const runtime = runtimePlatform || this.runtimePlatform;
+    const runner = startShellProcess({
+      command,
+      cwd,
+      runtimePlatform: runtime,
+      onOutput: (stream, text) => {
+        const prefix = stream === 'stderr' ? '[stderr] ' : '';
+        this.store.appendLog(task.sessionId, task.id, prefix ? text.split(/(\n)/).map(part => part === '\n' ? part : (part ? `${prefix}${part}` : part)).join('') : text);
+        this.refreshTaskLog(task.sessionId, task.id);
+      },
+      onExit: ({ code, signal }) => {
+        this.#completeTask(task.sessionId, task.id, {
+          status: code === 0 ? TASK_STATUS.SUCCEEDED : TASK_STATUS.FAILED,
+          exitCode: code,
+          signal,
+        });
+      },
+      onError: (err) => {
+        this.#completeTask(task.sessionId, task.id, {
+          status: TASK_STATUS.FAILED,
+          error: err?.message || String(err),
+        });
+      },
+    });
+
+    task.runtime.pid = runner.pid;
+    this.processes.set(this.#key(task.sessionId, task.id), runner);
+    this.store.writeTask(task);
+    this.#emit('updated', task);
+    return publicSnapshot(task);
+  }
+
+  #completeTask(sessionId, taskId, { status, exitCode = null, signal = null, error = null } = {}) {
+    const key = this.#key(sessionId, taskId);
+    const task = this.active.get(key) || this.store.readTask(sessionId, taskId);
+    if (!task || isTerminalTaskStatus(task.status)) return publicSnapshot(task);
+    const logPath = task.log?.path || this.store.logPath(sessionId, taskId);
+    const tail = this.store.readLogFile(logPath, { tail: true, maxBytes: LOG_PREVIEW_BYTES });
+    task.status = status || TASK_STATUS.FAILED;
+    task.updatedAt = nowIso();
+    task.endedAt = nowIso();
+    task.log = { ...(task.log || {}), path: tail.path, bytes: tail.bytes, preview: tail.text };
+    task.result = { ...(task.result || {}), exitCode, signal, error };
+    this.store.writeTask(task);
+    this.store.appendEvent(sessionId, { event: 'completed', taskId, status: task.status, exitCode, signal, error });
+    this.active.delete(key);
+    this.processes.delete(key);
+    this.#persistLifecycleMessage(task, 'finished', {
+      exitCode,
+      signal,
+      summary: error || `Task ${task.status}`,
+      logTail: tail.text,
+    });
+    this.#emit('completed', task);
+    return publicSnapshot(task);
+  }
+
+  cancelTask(sessionId, taskId) {
+    const key = this.#key(sessionId, taskId);
+    const task = this.active.get(key) || this.store.readTask(sessionId, taskId);
+    if (!task) return { ok: false, error: `Unknown task: ${taskId}` };
+    if (isTerminalTaskStatus(task.status)) return { ok: true, task: publicSnapshot(task) };
+    const runner = this.processes.get(key);
+    const killed = runner ? runner.kill('SIGTERM') : false;
+    if (!killed) {
+      return {
+        ok: false,
+        error: 'Unable to cancel task: no live process handle or process-tree kill failed.',
+        task: publicSnapshot(task),
+      };
+    }
+    const completed = this.#completeTask(sessionId, taskId, {
+      status: TASK_STATUS.CANCELLED,
+      signal: 'SIGTERM',
+    });
+    return { ok: true, task: completed };
+  }
+
+  listActiveTasks(sessionId = null) {
+    const tasks = Array.from(this.active.values()).filter(task => !sessionId || task.sessionId === sessionId);
+    return tasks.map(publicSnapshot);
+  }
+
+  getTask(sessionId, taskId) {
+    return publicSnapshot(this.active.get(this.#key(sessionId, taskId)) || this.store.readTask(sessionId, taskId));
+  }
+
+  readTaskLog(sessionId, taskId, opts = {}) {
+    const task = this.active.get(this.#key(sessionId, taskId)) || this.store.readTask(sessionId, taskId);
+    if (task?.log?.path) return this.store.readLogFile(task.log.path, opts);
+    return this.store.readLog(sessionId, taskId, opts);
+  }
+
+  setTaskLogPath(sessionId, taskId, logPath) {
+    if (!logPath || typeof logPath !== 'string') return null;
+    const key = this.#key(sessionId, taskId);
+    const task = this.active.get(key) || this.store.readTask(sessionId, taskId);
+    if (!task) return null;
+    task.log = { ...(task.log || {}), path: logPath };
+    task.updatedAt = nowIso();
+    this.store.writeTask(task);
+    if (!isTerminalTaskStatus(task.status)) this.active.set(key, task);
+    return this.refreshTaskLog(sessionId, taskId);
+  }
+
+  refreshTaskLog(sessionId, taskId) {
+    const key = this.#key(sessionId, taskId);
+    const task = this.active.get(key) || this.store.readTask(sessionId, taskId);
+    if (!task) return null;
+    const logPath = task.log?.path || this.store.logPath(sessionId, taskId);
+    const tail = this.store.readLogFile(logPath, { tail: true, maxBytes: LOG_PREVIEW_BYTES });
+    task.log = { ...(task.log || {}), path: tail.path, bytes: tail.bytes, preview: tail.text };
+    task.updatedAt = nowIso();
+    this.store.writeTask(task);
+    if (!isTerminalTaskStatus(task.status)) this.active.set(key, task);
+    this.#emit('updated', task);
+    return publicSnapshot(task);
+  }
+
+  renderActiveTasksForPrompt(sessionId = null) {
+    const tasks = this.listActiveTasks(sessionId);
+    if (tasks.length === 0) return '';
+    const lines = ['<active_tasks>'];
+    for (const task of tasks) {
+      const preview = (task.log?.preview || '').trim().split('\n').slice(-3).join(' | ');
+      lines.push(`- ${task.id} | ${task.kind} | ${task.status} | owner=${task.ownerVpId || 'unknown'} | title=${JSON.stringify(task.title)} | log=${task.log?.path || ''}${preview ? ` | tail=${JSON.stringify(preview)}` : ''}`);
+    }
+    lines.push('</active_tasks>');
+    return lines.join('\n');
+  }
+}

package/yeaft/tasks/shell-runner.js

@@ -0,0 +1,64 @@
+/**
+ * shell-runner.js — Cross-platform background shell task runner.
+ */
+
+import { spawn, spawnSync } from 'child_process';
+import { buildShellInvocation, getRuntimePlatformInfo } from '../runtime-platform.js';
+
+export function buildWindowsTaskkillArgs(pid) {
+  return ['/pid', String(pid), '/t', '/f'];
+}
+
+export function killShellProcessTree(pid, runtimePlatform, signal = 'SIGTERM') {
+  if (!pid) return false;
+  const platform = runtimePlatform || getRuntimePlatformInfo();
+  if (platform.isWindows) {
+    const result = spawnSync('taskkill.exe', buildWindowsTaskkillArgs(pid), {
+      windowsHide: true,
+      stdio: 'ignore',
+    });
+    return result.status === 0;
+  }
+
+  try {
+    process.kill(-pid, signal);
+    return true;
+  } catch {
+    try {
+      process.kill(pid, signal);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+export function startShellProcess({ command, cwd, runtimePlatform, onOutput, onExit, onError }) {
+  const platform = runtimePlatform || getRuntimePlatformInfo();
+  const invocation = buildShellInvocation(command, { runtimePlatform: platform });
+  const proc = spawn(invocation.command, invocation.args, {
+    cwd,
+    env: { ...process.env, TERM: 'dumb', FORCE_COLOR: '0' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    detached: !platform.isWindows,
+    windowsHide: true,
+  });
+
+  const write = (stream, chunk) => {
+    if (!chunk) return;
+    const text = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+    onOutput?.(stream, text);
+  };
+
+  proc.stdout?.on('data', (chunk) => write('stdout', chunk));
+  proc.stderr?.on('data', (chunk) => write('stderr', chunk));
+  proc.on('error', (err) => onError?.(err));
+  proc.on('close', (code, signal) => onExit?.({ code, signal }));
+
+  return {
+    pid: proc.pid || null,
+    kill(signal = 'SIGTERM') {
+      return killShellProcessTree(proc.pid, platform, signal);
+    },
+  };
+}

package/yeaft/tasks/store.js

@@ -0,0 +1,167 @@
+/**
+ * store.js — Persistent Session task metadata store.
+ *
+ * Tasks are Session-scoped runtime facts. Metadata is stored separately from
+ * logs so a noisy process cannot corrupt the task index.
+ */
+
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from 'fs';
+import { join } from 'path';
+
+export const TASK_STATUS = Object.freeze({
+  RUNNING: 'running',
+  SUCCEEDED: 'succeeded',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled',
+  ORPHANED: 'orphaned',
+});
+
+const TERMINAL = new Set([
+  TASK_STATUS.SUCCEEDED,
+  TASK_STATUS.FAILED,
+  TASK_STATUS.CANCELLED,
+  TASK_STATUS.ORPHANED,
+]);
+
+export function isTerminalTaskStatus(status) {
+  return TERMINAL.has(status);
+}
+
+function safeSessionId(sessionId) {
+  const raw = typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : 'default';
+  return raw.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+function safeTaskId(taskId) {
+  const raw = typeof taskId === 'string' && taskId.trim() ? taskId.trim() : 'task_unknown';
+  return raw.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+export class TaskStore {
+  constructor({ yeaftDir }) {
+    if (!yeaftDir) throw new Error('TaskStore requires yeaftDir');
+    this.yeaftDir = yeaftDir;
+    this.root = join(yeaftDir, 'tasks', 'sessions');
+  }
+
+  sessionDir(sessionId) {
+    return join(this.root, safeSessionId(sessionId));
+  }
+
+  taskPath(sessionId, taskId) {
+    return join(this.sessionDir(sessionId), `${safeTaskId(taskId)}.json`);
+  }
+
+  logPath(sessionId, taskId) {
+    return join(this.sessionDir(sessionId), `${safeTaskId(taskId)}.log`);
+  }
+
+  eventPath(sessionId) {
+    return join(this.sessionDir(sessionId), 'tasks.jsonl');
+  }
+
+  ensureSessionDir(sessionId) {
+    const dir = this.sessionDir(sessionId);
+    mkdirSync(dir, { recursive: true, mode: 0o755 });
+    return dir;
+  }
+
+  writeTask(task) {
+    if (!task?.id) throw new Error('TaskStore.writeTask requires task.id');
+    const sessionId = task.sessionId || 'default';
+    this.ensureSessionDir(sessionId);
+    writeFileSync(this.taskPath(sessionId, task.id), `${JSON.stringify(task, null, 2)}\n`, { encoding: 'utf8', mode: 0o644 });
+    return task;
+  }
+
+  appendEvent(sessionId, event) {
+    this.ensureSessionDir(sessionId);
+    appendFileSync(this.eventPath(sessionId), `${JSON.stringify({ ...event, at: event.at || new Date().toISOString() })}\n`, { encoding: 'utf8', mode: 0o644 });
+  }
+
+  appendLog(sessionId, taskId, chunk) {
+    if (typeof chunk !== 'string' || chunk.length === 0) return;
+    this.ensureSessionDir(sessionId);
+    appendFileSync(this.logPath(sessionId, taskId), chunk, { encoding: 'utf8', mode: 0o644 });
+  }
+
+  readLogFile(path, { offset = 0, maxBytes = 64 * 1024, tail = false } = {}) {
+    if (!existsSync(path)) return { path, text: '', bytes: 0, offset: 0, nextOffset: 0 };
+    const st = statSync(path);
+    const bytes = st.size;
+    let start = Math.max(0, Number.isFinite(offset) ? Math.floor(offset) : 0);
+    const cap = Math.max(0, Math.min(Number.isFinite(maxBytes) ? Math.floor(maxBytes) : 64 * 1024, 1024 * 1024));
+    if (tail) start = Math.max(0, bytes - cap);
+    const end = Math.min(bytes, start + cap);
+    const length = Math.max(0, end - start);
+    if (length === 0) {
+      return { path, text: '', bytes, offset: start, nextOffset: end, truncated: end < bytes };
+    }
+
+    const fd = openSync(path, 'r');
+    try {
+      const buf = Buffer.allocUnsafe(length);
+      const readBytes = readSync(fd, buf, 0, length, start);
+      return {
+        path,
+        text: buf.subarray(0, readBytes).toString('utf8'),
+        bytes,
+        offset: start,
+        nextOffset: start + readBytes,
+        truncated: start + readBytes < bytes,
+      };
+    } finally {
+      closeSync(fd);
+    }
+  }
+
+  readLog(sessionId, taskId, opts = {}) {
+    return this.readLogFile(this.logPath(sessionId, taskId), opts);
+  }
+
+  readTask(sessionId, taskId) {
+    const path = this.taskPath(sessionId, taskId);
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+  }
+
+  loadActiveTasks() {
+    if (!existsSync(this.root)) return [];
+    const out = [];
+    for (const sessionDirName of readdirSync(this.root, { withFileTypes: true })) {
+      if (!sessionDirName.isDirectory()) continue;
+      const sessionDir = join(this.root, sessionDirName.name);
+      for (const entry of readdirSync(sessionDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+        try {
+          const task = JSON.parse(readFileSync(join(sessionDir, entry.name), 'utf8'));
+          if (task && task.status === TASK_STATUS.RUNNING) out.push(task);
+        } catch {
+          // Ignore corrupt task metadata; one bad task must not block boot.
+        }
+      }
+    }
+    return out;
+  }
+
+  statLog(sessionId, taskId) {
+    const path = this.logPath(sessionId, taskId);
+    try {
+      const st = statSync(path);
+      return { path, bytes: st.size, mtimeMs: st.mtimeMs };
+    } catch {
+      return { path, bytes: 0, mtimeMs: 0 };
+    }
+  }
+}

package/yeaft/tools/agent.js

@@ -419,6 +419,15 @@ use it as the default workflow or call it repeatedly in a loop.`,
     const deps = ctx?.parentEngineDeps;
     if (deps && deps.adapter) {
       try {
+        const task = ctx?.taskManager?.startTask?.({
+          sessionId: callerScope.sessionId || ctx?.sessionId || 'default',
+          ownerVpId: callerScope.parentVpId || ctx?.currentVpId || null,
+          kind: 'sub_agent',
+          title: spec.mission || spec.task || name,
+          runtime: { subAgentId: agentId, name, cwd: agent.cwd },
+          source: { threadId: callerScope.parentThreadId || ctx?.threadId || 'main' },
+        });
+        if (task?.id) agent.taskId = task.id;
         startSubAgent(agent, deps);
       } catch (err) {
         agent.status = STATUS.FAILED;
@@ -449,6 +458,7 @@ use it as the default workflow or call it repeatedly in a loop.`,
       budget: spec.budget || null,
       status: agent.status,
       outputFile: agent.outputFile || null,
+      taskId: agent.taskId || null,
       liveness,
       stale: liveness.stale,
       stalled: liveness.stalled,

package/yeaft/tools/bash.js

@@ -12,7 +12,9 @@ import { defineTool } from './types.js';
 import { spawn } from 'child_process';
 import { existsSync } from 'fs';
 import { resolve } from 'path';
-import { getRuntimePlatformInfo, resolveDefaultShell } from '../runtime-platform.js';
+import { buildShellInvocation, getRuntimePlatformInfo } from '../runtime-platform.js';
+
+export { buildShellInvocation };
 
 /** Max output size in bytes before truncation (256 KB). */
 const MAX_OUTPUT = 256 * 1024;
@@ -23,31 +25,6 @@ const DEFAULT_TIMEOUT_MS = 120_000;
 /** Max timeout in ms (10 minutes). */
 const MAX_TIMEOUT_MS = 600_000;
 
-/**
- * @param {string} command
- * @param {{ runtimePlatform?: object }} opts
- */
-export function buildShellInvocation(command, opts = {}) {
-  const runtimePlatform = opts.runtimePlatform || getRuntimePlatformInfo();
-  const shell = runtimePlatform.defaultShell
-    ? {
-        command: runtimePlatform.defaultShell,
-        argsPrefix: Array.isArray(runtimePlatform.shellArgsPrefix) ? runtimePlatform.shellArgsPrefix : null,
-        family: runtimePlatform.shellFamily,
-      }
-    : resolveDefaultShell({ platform: runtimePlatform.platform });
-
-  const argsPrefix = Array.isArray(shell.argsPrefix)
-    ? shell.argsPrefix
-    : resolveDefaultShell({ platform: runtimePlatform.platform }).argsPrefix;
-
-  return {
-    command: shell.command,
-    args: [...argsPrefix, command],
-    family: shell.family || runtimePlatform.shellFamily || 'posix',
-  };
-}
-
 /**
  * Run a command in a child process.
  * @returns {Promise<{ stdout: string, stderr: string, exitCode: number, timedOut: boolean }>}
@@ -169,7 +146,7 @@ Guidelines:
 - Large outputs are truncated at 256KB
 - Use absolute paths when possible
 - Avoid interactive commands (no stdin support)
-- For long-running tasks, consider redirecting output to a file
+- Use background=true for long-running or persistent tasks that should survive across turns
 - stderr is captured separately and included in the result`,
     zh: `执行 Shell 命令并返回输出。
 
@@ -181,7 +158,7 @@ Guidelines:
 - 大输出在 256KB 处截断
 - 尽量使用绝对路径
 - 避免交互式命令（不支持 stdin）
-- 长时间任务建议重定向输出到文件
+- 长时间或需要跨 turn 持续存在的任务使用 background=true
 - stderr 单独捕获并包含在结果中`
   },
   parameters: {
@@ -208,6 +185,20 @@ Guidelines:
           zh: `超时时间，单位毫秒（默认 ${DEFAULT_TIMEOUT_MS}，最大 ${MAX_TIMEOUT_MS}）`,
         },
       },
+      background: {
+        type: 'boolean',
+        description: {
+          en: 'Run as a persistent Session task and return immediately with a taskId and log path',
+          zh: '作为持久化 Session 后台任务运行，并立即返回 taskId 和日志路径',
+        },
+      },
+      taskTitle: {
+        type: 'string',
+        description: {
+          en: 'Human-readable title for the background task',
+          zh: '后台任务的人类可读标题',
+        },
+      },
     },
     required: ['command'],
   },
@@ -223,7 +214,7 @@ Guidelines:
            cmd.includes('> /dev/') || cmd.includes('chmod 000');
   },
   async execute(input, ctx) {
-    const { command, cwd: inputCwd, timeout_ms } = input;
+    const { command, cwd: inputCwd, timeout_ms, background = false, taskTitle } = input;
     if (!command) return JSON.stringify({ error: 'command is required' });
 
     // Resolve working directory
@@ -239,6 +230,28 @@ Guidelines:
     const timeout = Math.min(Math.max(timeout_ms || DEFAULT_TIMEOUT_MS, 1000), MAX_TIMEOUT_MS);
     const runtimePlatform = ctx?.runtimePlatform || getRuntimePlatformInfo();
 
+    if (background) {
+      if (!ctx?.taskManager) {
+        return JSON.stringify({ error: 'background tasks are unavailable in this runtime' });
+      }
+      try {
+        const task = ctx.taskManager.startShellTask({
+          command,
+          cwd,
+          sessionId: ctx.sessionId || 'default',
+          ownerVpId: ctx.currentVpId || null,
+          title: taskTitle || command.slice(0, 120),
+          runtimePlatform,
+          source: {
+            threadId: ctx.threadId || 'main',
+          },
+        });
+        return `Started background task ${task.id}.\nStatus: ${task.status}\nLog: ${task.log?.path || ''}\nUse ListTasks, ReadTaskLog, or CancelTask to inspect or control it.`;
+      } catch (err) {
+        return JSON.stringify({ error: err?.message || String(err) });
+      }
+    }
+
     try {
       const result = await runCommand(command, {
         cwd,

package/yeaft/tools/cancel-task.js

@@ -0,0 +1,30 @@
+/**
+ * cancel-task.js — Cancel a running background task.
+ */
+
+import { defineTool } from './types.js';
+
+export default defineTool({
+  name: 'CancelTask',
+  description: {
+    en: 'Cancel a running Session background task.',
+    zh: '取消正在运行的 Session 后台任务。',
+  },
+  parameters: {
+    type: 'object',
+    properties: {
+      taskId: { type: 'string', description: { en: 'Task id', zh: '任务 ID' } },
+      sessionId: { type: 'string', description: { en: 'Session id (defaults to current Session)', zh: 'Session ID（默认当前 Session）' } },
+    },
+    required: ['taskId'],
+  },
+  isConcurrencySafe: () => false,
+  isReadOnly: () => false,
+  async execute(input = {}, ctx = {}) {
+    if (!ctx.taskManager) return JSON.stringify({ error: 'task manager unavailable' });
+    const taskId = input.taskId;
+    if (!taskId) return JSON.stringify({ error: 'taskId is required' });
+    const sessionId = input.sessionId || ctx.sessionId || 'default';
+    return JSON.stringify(ctx.taskManager.cancelTask(sessionId, taskId), null, 2);
+  },
+});

package/yeaft/tools/close-agent.js

@@ -95,6 +95,14 @@ Do NOT end your turn silently right after CloseAgent.`,
     const wasTerminal = isTerminalAgentStatus(agent.status);
     if (!wasTerminal) {
       agent.status = STATUS.CLOSED;
+      if (agent.taskId && ctx?.taskManager && agent.parentSessionId) {
+        try {
+          ctx.taskManager.completeTask(agent.parentSessionId, agent.taskId, {
+            status: 'cancelled',
+            error: agent.error || null,
+          });
+        } catch { /* ignore */ }
+      }
       // The driver may not yet have observed the abort / status flip; push
       // a notification so the queue stays consistent (idempotent inside
       // the notifications module). The driver's own finalizeTerminal()

package/yeaft/tools/index.js

@@ -38,6 +38,9 @@ import globTool from './glob.js';
 import grepTool from './grep.js';
 import listDir from './list-dir.js';
 import applyPatch from './apply-patch.js';
+import listTasks from './list-tasks.js';
+import readTaskLog from './read-task-log.js';
+import cancelTask from './cancel-task.js';
 
 // --- P1 Agent tools ---
 import agentTool from './agent.js';
@@ -99,6 +102,9 @@ export const allTools = [
   grepTool,
   listDir,
   applyPatch,
+  listTasks,
+  readTaskLog,
+  cancelTask,
 
   // P1 Agent
   agentTool,

package/yeaft/tools/list-tasks.js

@@ -0,0 +1,29 @@
+/**
+ * list-tasks.js — List active Session background tasks.
+ */
+
+import { defineTool } from './types.js';
+
+export default defineTool({
+  name: 'ListTasks',
+  description: {
+    en: 'List currently running Session background tasks.',
+    zh: '列出当前正在运行的 Session 后台任务。',
+  },
+  parameters: {
+    type: 'object',
+    properties: {
+      sessionId: {
+        type: 'string',
+        description: { en: 'Session id (defaults to current Session)', zh: 'Session ID（默认当前 Session）' },
+      },
+    },
+  },
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input = {}, ctx = {}) {
+    if (!ctx.taskManager) return JSON.stringify({ error: 'task manager unavailable' });
+    const sessionId = input.sessionId || ctx.sessionId || null;
+    return JSON.stringify({ tasks: ctx.taskManager.listActiveTasks(sessionId) }, null, 2);
+  },
+});

package/yeaft/tools/read-task-log.js

@@ -0,0 +1,38 @@
+/**
+ * read-task-log.js — Read a background task log.
+ */
+
+import { defineTool } from './types.js';
+
+export default defineTool({
+  name: 'ReadTaskLog',
+  description: {
+    en: 'Read a background task log by taskId. Supports tail reads and byte offsets.',
+    zh: '按 taskId 读取后台任务日志。支持 tail 和字节 offset。',
+  },
+  parameters: {
+    type: 'object',
+    properties: {
+      taskId: { type: 'string', description: { en: 'Task id', zh: '任务 ID' } },
+      sessionId: { type: 'string', description: { en: 'Session id (defaults to current Session)', zh: 'Session ID（默认当前 Session）' } },
+      offset: { type: 'number', description: { en: 'Byte offset to start reading from', zh: '开始读取的字节 offset' } },
+      maxBytes: { type: 'number', description: { en: 'Maximum bytes to read (max 1 MiB)', zh: '最多读取字节数（最大 1 MiB）' } },
+      tail: { type: 'boolean', description: { en: 'Read the last maxBytes bytes', zh: '读取最后 maxBytes 字节' } },
+    },
+    required: ['taskId'],
+  },
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input = {}, ctx = {}) {
+    if (!ctx.taskManager) return JSON.stringify({ error: 'task manager unavailable' });
+    const taskId = input.taskId;
+    if (!taskId) return JSON.stringify({ error: 'taskId is required' });
+    const sessionId = input.sessionId || ctx.sessionId || 'default';
+    const result = ctx.taskManager.readTaskLog(sessionId, taskId, {
+      offset: input.offset,
+      maxBytes: input.maxBytes,
+      tail: input.tail !== false,
+    });
+    return JSON.stringify(result, null, 2);
+  },
+});

package/yeaft/tools/types.js

@@ -21,6 +21,9 @@
  * @property {object} [skillManager] — Skill manager
  * @property {object} [trace] — debug trace
  * @property {object} [config] — engine config
+ * @property {import('../tasks/manager.js').TaskManager} [taskManager] — Session task manager
+ * @property {string} [sessionId] — current Session id
+ * @property {string} [threadId] — current Session thread id
  * @property {string} [currentVpId] — R6: VP id of the caller (set in multi-VP groups)
  * @property {string} [currentGroupId] — R6: group id of the caller's RoleInstance
  * @property {(sessionId: string) => string[]|null} [getGroupRoster]

package/yeaft/web-bridge.js

@@ -948,6 +948,7 @@ function getOrCreateVpEngine(sessionId, vpId, threadId = 'main') {
     // (`if (this.#toolStats && ...)`) is false and group VP tool calls
     // are silently dropped.
     toolStats: session.toolStats || null,
+    taskManager: session.taskManager || null,
     // Per-VP fan-out: bind the engine to its (sessionId, vpId) so post-turn
     // compact reads/writes a scoped summary instead of the legacy global
     // compact.md (which every VP would otherwise share, producing
@@ -1943,6 +1944,15 @@ function buildVpPersona(vpId) {
 export function installYeaftRuntimeBridge(s) {
   if (!s) return;
 
+  if (s.taskManager && typeof s.taskManager.setEventSink === 'function') {
+    s.taskManager.setEventSink((event) => {
+      try {
+        const sessionId = event?.task?.sessionId || event?.sessionId || null;
+        sendSessionEvent(event, { sessionId });
+      } catch { /* never let task event delivery throw */ }
+    });
+  }
+
   // Forward dream pipeline progress events to the web debug panel.
   //
   // Group-id stamping is NO LONGER done here. It used to be: this sink
@@ -2896,6 +2906,7 @@ async function ensureSessionLoaded() {
     mcpServers: session.status.mcpServers,
     tools: session.status.tools,
     yeaftDir: ctx.CONFIG?.yeaftDir || null,
+    tasks: session.taskManager ? session.taskManager.listActiveTasks() : [],
   });
   sendSessionSnapshotBroadcast();
   // vp-status: rebuild frontend status table from authoritative agent
@@ -4152,6 +4163,7 @@ export async function handleYeaftLoadHistory(msg) {
     mcpServers: session.status.mcpServers,
     tools: session.status.tools,
     yeaftDir: ctx.CONFIG?.yeaftDir || null,
+    tasks: session.taskManager ? session.taskManager.listActiveTasks() : [],
   });
   sendSessionSnapshotBroadcast();
   if (sessionId) {