codeharbor 0.1.8 → 0.1.10

package/.env.example

@@ -17,6 +17,11 @@ CODEX_EXTRA_ARGS=
 # Optional JSON object for additional environment variables passed to codex child process.
 CODEX_EXTRA_ENV_JSON=
 
+# Multi-agent workflow (Phase B, opt-in).
+AGENT_WORKFLOW_ENABLED=false
+# Auto-repair rounds after reviewer rejects output.
+AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS=1
+
 # SQLite state database path.
 STATE_DB_PATH=data/state.db
 # Legacy JSON path for one-time migration import.

package/README.md

@@ -67,27 +67,33 @@ curl -fsSL https://raw.githubusercontent.com/biglone/CodeHarbor/main/scripts/ins
 Install first, then enable systemd service with one command:
 
 ```bash
-sudo "$(command -v codeharbor)" service install
+codeharbor service install
 ```
 
 Install + enable main and admin services:
 
 ```bash
-sudo "$(command -v codeharbor)" service install --with-admin
+codeharbor service install --with-admin
 ```
 
 Restart installed service(s):
 
 ```bash
-sudo "$(command -v codeharbor)" service restart --with-admin
+codeharbor service restart --with-admin
 ```
 
 Remove installed services:
 
 ```bash
-sudo "$(command -v codeharbor)" service uninstall --with-admin
+codeharbor service uninstall --with-admin
 ```
 
+Notes:
+
+- Service commands auto-elevate with `sudo` when root privileges are required.
+- If your environment blocks interactive `sudo`, use explicit fallback:
+  - `sudo <node-bin> <codeharbor-cli-script> service ...`
+
 Enable Admin service at install time:
 
 ```bash
@@ -391,6 +397,17 @@ If any check fails, it prints actionable fix commands (for example `codeharbor i
   - `/status` show session + limiter + metrics + runtime worker status
   - `/reset` clear bound Codex session and keep conversation active
   - `/stop` cancel in-flight execution (if running) and reset session context
+  - `/agents status` show multi-agent workflow status for current session (when enabled)
+  - `/agents run <objective>` run Planner -> Executor -> Reviewer workflow (when enabled)
+
+### Multi-Agent Workflow (Phase B, Opt-In)
+
+- `AGENT_WORKFLOW_ENABLED=true`
+  - enable `/agents` workflow commands
+- `AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS`
+  - reviewer reject loop upper bound (default `1`)
+
+Default is disabled to keep legacy behavior unchanged.
 
 ## CLI Compatibility Mode
 

package/dist/cli.js

@@ -24,6 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli.ts
+var import_node_child_process6 = require("child_process");
 var import_node_fs11 = __toESM(require("fs"));
 var import_node_path12 = __toESM(require("path"));
 var import_commander = require("commander");
@@ -599,6 +600,27 @@ var AdminServer = class {
         updatedKeys.push("cliCompat.fetchMedia");
       }
     }
+    if ("agentWorkflow" in body) {
+      const workflow = asObject(body.agentWorkflow, "agentWorkflow");
+      const currentAgentWorkflow = ensureAgentWorkflowConfig(this.config);
+      if ("enabled" in workflow) {
+        const value = normalizeBoolean(workflow.enabled, currentAgentWorkflow.enabled);
+        currentAgentWorkflow.enabled = value;
+        envUpdates.AGENT_WORKFLOW_ENABLED = String(value);
+        updatedKeys.push("agentWorkflow.enabled");
+      }
+      if ("autoRepairMaxRounds" in workflow) {
+        const value = normalizePositiveInt(
+          workflow.autoRepairMaxRounds,
+          currentAgentWorkflow.autoRepairMaxRounds,
+          0,
+          10
+        );
+        currentAgentWorkflow.autoRepairMaxRounds = value;
+        envUpdates.AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS = String(value);
+        updatedKeys.push("agentWorkflow.autoRepairMaxRounds");
+      }
+    }
     if (updatedKeys.length === 0) {
       throw new HttpError(400, "No supported global config fields provided.");
     }
@@ -719,8 +741,22 @@ function buildGlobalConfigSnapshot(config) {
     matrixProgressMinIntervalMs: config.matrixProgressMinIntervalMs,
     matrixTypingTimeoutMs: config.matrixTypingTimeoutMs,
     sessionActiveWindowMinutes: config.sessionActiveWindowMinutes,
-    cliCompat: { ...config.cliCompat }
+    cliCompat: { ...config.cliCompat },
+    agentWorkflow: { ...ensureAgentWorkflowConfig(config) }
+  };
+}
+function ensureAgentWorkflowConfig(config) {
+  const mutable = config;
+  const existing = mutable.agentWorkflow;
+  if (existing && typeof existing.enabled === "boolean" && Number.isFinite(existing.autoRepairMaxRounds)) {
+    return existing;
+  }
+  const fallback = {
+    enabled: false,
+    autoRepairMaxRounds: 1
   };
+  mutable.agentWorkflow = fallback;
+  return fallback;
 }
 function formatAuditEntry(entry) {
   return {
@@ -1221,6 +1257,11 @@ var ADMIN_CONSOLE_HTML = `<!doctype html>
             <input id="global-cli-throttle" type="number" min="0" />
           </label>
           <label class="checkbox"><input id="global-cli-fetch-media" type="checkbox" /><span>Fetch media attachments</span></label>
+          <label class="checkbox"><input id="global-agent-enabled" type="checkbox" /><span>Enable multi-agent workflow</span></label>
+          <label class="field">
+            <span class="field-label">Workflow auto-repair rounds</span>
+            <input id="global-agent-repair-rounds" type="number" min="0" max="10" />
+          </label>
         </div>
         <div class="actions">
           <button id="global-save-btn" type="button">Save Global Config</button>
@@ -1488,6 +1529,7 @@ var ADMIN_CONSOLE_HTML = `<!doctype html>
             var rateLimiter = data.rateLimiter || {};
             var trigger = data.defaultGroupTriggerPolicy || {};
             var cliCompat = data.cliCompat || {};
+            var agentWorkflow = data.agentWorkflow || {};
 
             document.getElementById("global-matrix-prefix").value = data.matrixCommandPrefix || "";
             document.getElementById("global-workdir").value = data.codexWorkdir || "";
@@ -1513,6 +1555,10 @@ var ADMIN_CONSOLE_HTML = `<!doctype html>
             document.getElementById("global-cli-disable-split").checked = Boolean(cliCompat.disableReplyChunkSplit);
             document.getElementById("global-cli-throttle").value = String(cliCompat.progressThrottleMs || 0);
             document.getElementById("global-cli-fetch-media").checked = Boolean(cliCompat.fetchMedia);
+            document.getElementById("global-agent-enabled").checked = Boolean(agentWorkflow.enabled);
+            document.getElementById("global-agent-repair-rounds").value = String(
+              typeof agentWorkflow.autoRepairMaxRounds === "number" ? agentWorkflow.autoRepairMaxRounds : 1
+            );
 
             showNotice("ok", "Global config loaded.");
           } catch (error) {
@@ -1550,6 +1596,10 @@ var ADMIN_CONSOLE_HTML = `<!doctype html>
                 disableReplyChunkSplit: asBool("global-cli-disable-split"),
                 progressThrottleMs: asNumber("global-cli-throttle", 300),
                 fetchMedia: asBool("global-cli-fetch-media")
+              },
+              agentWorkflow: {
+                enabled: asBool("global-agent-enabled"),
+                autoRepairMaxRounds: asNumber("global-agent-repair-rounds", 1)
               }
             };
             var response = await apiRequest("/api/admin/config/global", "PUT", body);
@@ -2880,6 +2930,273 @@ function computeRetryAfter(timestamps, windowMs, now) {
   return Math.max(0, oldest + windowMs - now);
 }
 
+// src/workflow/multi-agent-workflow.ts
+var MultiAgentWorkflowRunner = class {
+  executor;
+  logger;
+  config;
+  constructor(executor, logger, config) {
+    this.executor = executor;
+    this.logger = logger;
+    this.config = config;
+  }
+  isEnabled() {
+    return this.config.enabled;
+  }
+  async run(input) {
+    const startedAt = Date.now();
+    const objective = input.objective.trim();
+    if (!objective) {
+      throw new Error("workflow objective cannot be empty.");
+    }
+    const maxRepairRounds = Math.max(0, this.config.autoRepairMaxRounds);
+    let plannerSessionId = null;
+    let executorSessionId = null;
+    let reviewerSessionId = null;
+    let activeHandle = null;
+    let cancelled = false;
+    input.onRegisterCancel?.(() => {
+      cancelled = true;
+      activeHandle?.cancel();
+    });
+    await emitProgress(input, {
+      stage: "planner",
+      round: 0,
+      message: "Planner \u6B63\u5728\u751F\u6210\u6267\u884C\u8BA1\u5212"
+    });
+    const planResult = await this.executeRole(
+      "planner",
+      buildPlannerPrompt(objective),
+      plannerSessionId,
+      input.workdir,
+      () => cancelled,
+      (handle) => {
+        activeHandle = handle;
+      }
+    );
+    plannerSessionId = planResult.sessionId;
+    const plan = planResult.reply;
+    await emitProgress(input, {
+      stage: "executor",
+      round: 0,
+      message: "Executor \u6B63\u5728\u6839\u636E\u8BA1\u5212\u6267\u884C\u4EFB\u52A1"
+    });
+    let outputResult = await this.executeRole(
+      "executor",
+      buildExecutorPrompt(objective, plan),
+      executorSessionId,
+      input.workdir,
+      () => cancelled,
+      (handle) => {
+        activeHandle = handle;
+      }
+    );
+    executorSessionId = outputResult.sessionId;
+    let finalReviewReply = "";
+    let approved = false;
+    let repairRounds = 0;
+    for (let attempt = 0; attempt <= maxRepairRounds; attempt += 1) {
+      await emitProgress(input, {
+        stage: "reviewer",
+        round: attempt,
+        message: `Reviewer \u6B63\u5728\u8FDB\u884C\u8D28\u91CF\u5BA1\u67E5\uFF08round ${attempt + 1}\uFF09`
+      });
+      const reviewResult = await this.executeRole(
+        "reviewer",
+        buildReviewerPrompt(objective, plan, outputResult.reply),
+        reviewerSessionId,
+        input.workdir,
+        () => cancelled,
+        (handle) => {
+          activeHandle = handle;
+        }
+      );
+      reviewerSessionId = reviewResult.sessionId;
+      finalReviewReply = reviewResult.reply;
+      const verdict = parseReviewerVerdict(finalReviewReply);
+      if (verdict.approved) {
+        approved = true;
+        break;
+      }
+      if (attempt >= maxRepairRounds) {
+        break;
+      }
+      repairRounds = attempt + 1;
+      await emitProgress(input, {
+        stage: "repair",
+        round: repairRounds,
+        message: `Executor \u6B63\u5728\u6309 Reviewer \u53CD\u9988\u8FDB\u884C\u4FEE\u590D\uFF08round ${repairRounds}\uFF09`
+      });
+      outputResult = await this.executeRole(
+        "executor",
+        buildRepairPrompt(objective, plan, outputResult.reply, verdict.feedback, repairRounds),
+        executorSessionId,
+        input.workdir,
+        () => cancelled,
+        (handle) => {
+          activeHandle = handle;
+        }
+      );
+      executorSessionId = outputResult.sessionId;
+    }
+    const durationMs = Date.now() - startedAt;
+    this.logger.info("Multi-agent workflow finished", {
+      objective,
+      approved,
+      repairRounds,
+      durationMs
+    });
+    return {
+      objective,
+      plan,
+      output: outputResult.reply,
+      review: finalReviewReply,
+      approved,
+      repairRounds,
+      durationMs
+    };
+  }
+  async executeRole(role, prompt, sessionId, workdir, getCancelled, setActiveHandle) {
+    if (getCancelled()) {
+      throw new CodexExecutionCancelledError("workflow cancelled");
+    }
+    const handle = this.executor.startExecution(prompt, sessionId, void 0, { workdir });
+    setActiveHandle(handle);
+    try {
+      const result = await handle.result;
+      return {
+        sessionId: result.sessionId,
+        reply: result.reply
+      };
+    } finally {
+      setActiveHandle(null);
+    }
+  }
+};
+async function emitProgress(input, event) {
+  if (!input.onProgress) {
+    return;
+  }
+  await input.onProgress(event);
+}
+function buildPlannerPrompt(objective) {
+  return [
+    "[role:planner]",
+    "\u4F60\u662F\u8F6F\u4EF6\u4EA4\u4ED8\u89C4\u5212\u4EE3\u7406\u3002\u8BF7\u57FA\u4E8E\u76EE\u6807\u7ED9\u51FA\u53EF\u6267\u884C\u8BA1\u5212\u3002",
+    "\u8F93\u51FA\u8981\u6C42\uFF1A",
+    "1. \u4EFB\u52A1\u62C6\u89E3\uFF083-7 \u6B65\uFF09",
+    "2. \u6BCF\u6B65\u8F93\u5165/\u8F93\u51FA",
+    "3. \u98CE\u9669\u4E0E\u56DE\u9000\u65B9\u6848",
+    "",
+    `\u76EE\u6807\uFF1A${objective}`
+  ].join("\n");
+}
+function buildExecutorPrompt(objective, plan) {
+  return [
+    "[role:executor]",
+    "\u4F60\u662F\u8F6F\u4EF6\u6267\u884C\u4EE3\u7406\u3002\u8BF7\u6839\u636E\u8BA1\u5212\u5B8C\u6210\u4EA4\u4ED8\u5185\u5BB9\u3002",
+    "\u8F93\u51FA\u8981\u6C42\uFF1A",
+    "1. \u76F4\u63A5\u7ED9\u51FA\u6700\u7EC8\u53EF\u6267\u884C\u7ED3\u679C",
+    "2. \u8BF4\u660E\u4F60\u5B9E\u9645\u5B8C\u6210\u4E86\u54EA\u4E9B\u6B65\u9AA4",
+    "3. \u5982\u679C\u9700\u8981\u6587\u4EF6\u843D\u76D8\uFF0C\u8BF7\u7ED9\u51FA\u7EDD\u5BF9\u8DEF\u5F84",
+    "",
+    `\u76EE\u6807\uFF1A${objective}`,
+    "",
+    "[planner_plan]",
+    plan,
+    "[/planner_plan]"
+  ].join("\n");
+}
+function buildReviewerPrompt(objective, plan, output) {
+  return [
+    "[role:reviewer]",
+    "\u4F60\u662F\u8D28\u91CF\u5BA1\u67E5\u4EE3\u7406\u3002\u8BF7\u4E25\u683C\u5BA1\u67E5\u6267\u884C\u7ED3\u679C\u662F\u5426\u8FBE\u6210\u76EE\u6807\u3002",
+    "\u8F93\u51FA\u683C\u5F0F\u5FC5\u987B\u5305\u542B\u4EE5\u4E0B\u5B57\u6BB5\uFF1A",
+    "VERDICT: APPROVED \u6216 REJECTED",
+    "SUMMARY: \u4E00\u53E5\u8BDD\u603B\u7ED3",
+    "ISSUES:",
+    "- issue 1",
+    "- issue 2",
+    "SUGGESTIONS:",
+    "- suggestion 1",
+    "- suggestion 2",
+    "",
+    `\u76EE\u6807\uFF1A${objective}`,
+    "",
+    "[planner_plan]",
+    plan,
+    "[/planner_plan]",
+    "",
+    "[executor_output]",
+    output,
+    "[/executor_output]"
+  ].join("\n");
+}
+function buildRepairPrompt(objective, plan, previousOutput, reviewerFeedback, round) {
+  return [
+    "[role:executor]",
+    `\u4F60\u662F\u8F6F\u4EF6\u6267\u884C\u4EE3\u7406\u3002\u8BF7\u6839\u636E\u5BA1\u67E5\u53CD\u9988\u8FDB\u884C\u7B2C ${round} \u8F6E\u4FEE\u590D\u5E76\u8F93\u51FA\u6700\u7EC8\u7248\u672C\u3002`,
+    "\u8981\u6C42\uFF1A\u4FDD\u6301\u6B63\u786E\u5185\u5BB9\uFF0C\u4FEE\u590D\u95EE\u9898\uFF0C\u4E0D\u8981\u4E22\u5931\u5DF2\u5B8C\u6210\u90E8\u5206\u3002",
+    "",
+    `\u76EE\u6807\uFF1A${objective}`,
+    "",
+    "[planner_plan]",
+    plan,
+    "[/planner_plan]",
+    "",
+    "[previous_output]",
+    previousOutput,
+    "[/previous_output]",
+    "",
+    "[reviewer_feedback]",
+    reviewerFeedback,
+    "[/reviewer_feedback]"
+  ].join("\n");
+}
+function parseReviewerVerdict(review) {
+  const approved = /\bVERDICT\s*:\s*APPROVED\b/i.test(review);
+  const rejected = /\bVERDICT\s*:\s*REJECTED\b/i.test(review);
+  if (approved) {
+    return { approved: true, feedback: review };
+  }
+  if (rejected) {
+    return { approved: false, feedback: review };
+  }
+  return {
+    approved: false,
+    feedback: review.trim() || "Reviewer \u672A\u8FD4\u56DE\u89C4\u8303 verdict\uFF0C\u9ED8\u8BA4\u6309 REJECTED \u5904\u7406\u3002"
+  };
+}
+function parseWorkflowCommand(text) {
+  const normalized = text.trim();
+  if (!normalized.startsWith("/agents")) {
+    return null;
+  }
+  const parts = normalized.split(/\s+/);
+  if (parts.length === 1 || parts[1]?.toLowerCase() === "status") {
+    return { kind: "status" };
+  }
+  if (parts[1]?.toLowerCase() !== "run") {
+    return null;
+  }
+  const objective = normalized.replace(/^\/agents\s+run\s*/i, "").trim();
+  return {
+    kind: "run",
+    objective
+  };
+}
+function createIdleWorkflowSnapshot() {
+  return {
+    state: "idle",
+    startedAt: null,
+    endedAt: null,
+    objective: null,
+    approved: null,
+    repairRounds: 0,
+    error: null
+  };
+}
+
 // src/orchestrator.ts
 var RequestMetrics = class {
   total = 0;
@@ -2965,6 +3282,8 @@ var Orchestrator = class {
   rateLimiter;
   cliCompat;
   cliCompatRecorder;
+  workflowRunner;
+  workflowSnapshots = /* @__PURE__ */ new Map();
   metrics = new RequestMetrics();
   lastLockPruneAt = 0;
   constructor(channel, executor, stateStore, logger, options) {
@@ -3011,6 +3330,10 @@ var Orchestrator = class {
         maxConcurrentPerRoom: 4
       }
     );
+    this.workflowRunner = new MultiAgentWorkflowRunner(this.executor, this.logger, {
+      enabled: options?.multiAgentWorkflow?.enabled ?? false,
+      autoRepairMaxRounds: options?.multiAgentWorkflow?.autoRepairMaxRounds ?? 1
+    });
     this.sessionRuntime = new CodexSessionRuntime(this.executor);
   }
   async handleMessage(message) {
@@ -3054,6 +3377,12 @@ var Orchestrator = class {
         this.stateStore.markEventProcessed(sessionKey, message.eventId);
         return;
       }
+      const workflowCommand = this.workflowRunner.isEnabled() ? parseWorkflowCommand(route.prompt) : null;
+      if (workflowCommand?.kind === "status") {
+        await this.handleWorkflowStatusCommand(sessionKey, message);
+        this.stateStore.markEventProcessed(sessionKey, message.eventId);
+        return;
+      }
       const rateDecision = this.rateLimiter.tryAcquire({
         userId: message.senderId,
         roomId: message.conversationId
@@ -3071,6 +3400,37 @@ var Orchestrator = class {
         });
         return;
       }
+      if (workflowCommand?.kind === "run") {
+        const executionStartedAt = Date.now();
+        let sendDurationMs2 = 0;
+        this.stateStore.activateSession(sessionKey, this.sessionActiveWindowMs);
+        try {
+          const sendStartedAt = Date.now();
+          await this.handleWorkflowRunCommand(
+            workflowCommand.objective,
+            sessionKey,
+            message,
+            requestId,
+            roomConfig.workdir
+          );
+          sendDurationMs2 += Date.now() - sendStartedAt;
+          this.stateStore.markEventProcessed(sessionKey, message.eventId);
+          this.metrics.record("success", queueWaitMs, Date.now() - executionStartedAt, sendDurationMs2);
+        } catch (error) {
+          sendDurationMs2 += await this.sendWorkflowFailure(message.conversationId, error);
+          this.stateStore.commitExecutionHandled(sessionKey, message.eventId);
+          const status = classifyExecutionOutcome(error);
+          this.metrics.record(status, queueWaitMs, Date.now() - executionStartedAt, sendDurationMs2);
+          this.logger.error("Workflow request failed", {
+            requestId,
+            sessionKey,
+            error: formatError2(error)
+          });
+        } finally {
+          rateDecision.release?.();
+        }
+        return;
+      }
       this.stateStore.activateSession(sessionKey, this.sessionActiveWindowMs);
       const previousCodexSessionId = this.stateStore.getCodexSessionId(sessionKey);
       const executionPrompt = this.buildExecutionPrompt(route.prompt, message);
@@ -3291,6 +3651,7 @@ var Orchestrator = class {
     const metrics = this.metrics.snapshot(this.runningExecutions.size);
     const limiter = this.rateLimiter.snapshot();
     const runtime = this.sessionRuntime.getRuntimeStats();
+    const workflow = this.workflowSnapshots.get(sessionKey) ?? createIdleWorkflowSnapshot();
     await this.channel.sendNotice(
       message.conversationId,
       `[CodeHarbor] \u5F53\u524D\u72B6\u6001
@@ -3303,9 +3664,122 @@ var Orchestrator = class {
 - \u6307\u6807: total=${metrics.total}, success=${metrics.success}, failed=${metrics.failed}, timeout=${metrics.timeout}, cancelled=${metrics.cancelled}, rate_limited=${metrics.rateLimited}
 - \u5E73\u5747\u8017\u65F6: queue=${metrics.avgQueueMs}ms, exec=${metrics.avgExecMs}ms, send=${metrics.avgSendMs}ms
 - \u9650\u6D41\u5E76\u53D1: global=${limiter.activeGlobal}, users=${limiter.activeUsers}, rooms=${limiter.activeRooms}
-- CLI runtime: workers=${runtime.workerCount}, running=${runtime.runningCount}, compat_mode=${this.cliCompat.enabled ? "on" : "off"}`
+- CLI runtime: workers=${runtime.workerCount}, running=${runtime.runningCount}, compat_mode=${this.cliCompat.enabled ? "on" : "off"}
+- Multi-Agent workflow: enabled=${this.workflowRunner.isEnabled() ? "on" : "off"}, state=${workflow.state}`
     );
   }
+  async handleWorkflowStatusCommand(sessionKey, message) {
+    const snapshot = this.workflowSnapshots.get(sessionKey) ?? createIdleWorkflowSnapshot();
+    await this.channel.sendNotice(
+      message.conversationId,
+      `[CodeHarbor] Multi-Agent \u5DE5\u4F5C\u6D41\u72B6\u6001
+- state: ${snapshot.state}
+- startedAt: ${snapshot.startedAt ?? "N/A"}
+- endedAt: ${snapshot.endedAt ?? "N/A"}
+- objective: ${snapshot.objective ?? "N/A"}
+- approved: ${snapshot.approved === null ? "N/A" : snapshot.approved ? "yes" : "no"}
+- repairRounds: ${snapshot.repairRounds}
+- error: ${snapshot.error ?? "N/A"}`
+    );
+  }
+  async handleWorkflowRunCommand(objective, sessionKey, message, requestId, workdir) {
+    const normalizedObjective = objective.trim();
+    if (!normalizedObjective) {
+      await this.channel.sendNotice(message.conversationId, "[CodeHarbor] /agents run \u9700\u8981\u63D0\u4F9B\u4EFB\u52A1\u76EE\u6807\u3002");
+      return;
+    }
+    const requestStartedAt = Date.now();
+    let progressNoticeEventId = null;
+    const progressCtx = {
+      conversationId: message.conversationId,
+      isDirectMessage: message.isDirectMessage,
+      getProgressNoticeEventId: () => progressNoticeEventId,
+      setProgressNoticeEventId: (next) => {
+        progressNoticeEventId = next;
+      }
+    };
+    const startedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+    this.workflowSnapshots.set(sessionKey, {
+      state: "running",
+      startedAt: startedAtIso,
+      endedAt: null,
+      objective: normalizedObjective,
+      approved: null,
+      repairRounds: 0,
+      error: null
+    });
+    const stopTyping = this.startTypingHeartbeat(message.conversationId);
+    let cancelWorkflow = () => {
+    };
+    let cancelRequested = false;
+    this.runningExecutions.set(sessionKey, {
+      requestId,
+      startedAt: requestStartedAt,
+      cancel: () => {
+        cancelRequested = true;
+        cancelWorkflow();
+      }
+    });
+    await this.sendProgressUpdate(progressCtx, "[CodeHarbor] Multi-Agent workflow \u542F\u52A8\uFF1APlanner -> Executor -> Reviewer");
+    try {
+      const result = await this.workflowRunner.run({
+        objective: normalizedObjective,
+        workdir,
+        onRegisterCancel: (cancel) => {
+          cancelWorkflow = cancel;
+          if (cancelRequested) {
+            cancelWorkflow();
+          }
+        },
+        onProgress: async (event) => {
+          const stepLabel = event.stage.toUpperCase();
+          await this.sendProgressUpdate(progressCtx, `[CodeHarbor] [${stepLabel}] ${event.message}`);
+        }
+      });
+      const endedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+      this.workflowSnapshots.set(sessionKey, {
+        state: "succeeded",
+        startedAt: startedAtIso,
+        endedAt: endedAtIso,
+        objective: normalizedObjective,
+        approved: result.approved,
+        repairRounds: result.repairRounds,
+        error: null
+      });
+      await this.channel.sendMessage(message.conversationId, buildWorkflowResultReply(result));
+      await this.finishProgress(progressCtx, `\u591A\u667A\u80FD\u4F53\u6D41\u7A0B\u5B8C\u6210\uFF08\u8017\u65F6 ${formatDurationMs(Date.now() - requestStartedAt)}\uFF09`);
+    } catch (error) {
+      const status = classifyExecutionOutcome(error);
+      const endedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+      this.workflowSnapshots.set(sessionKey, {
+        state: status === "cancelled" ? "idle" : "failed",
+        startedAt: startedAtIso,
+        endedAt: endedAtIso,
+        objective: normalizedObjective,
+        approved: null,
+        repairRounds: 0,
+        error: formatError2(error)
+      });
+      await this.finishProgress(progressCtx, buildFailureProgressSummary(status, requestStartedAt, error));
+      throw error;
+    } finally {
+      const running = this.runningExecutions.get(sessionKey);
+      if (running?.requestId === requestId) {
+        this.runningExecutions.delete(sessionKey);
+      }
+      await stopTyping();
+    }
+  }
+  async sendWorkflowFailure(conversationId, error) {
+    const startedAt = Date.now();
+    const status = classifyExecutionOutcome(error);
+    if (status === "cancelled") {
+      await this.channel.sendNotice(conversationId, "[CodeHarbor] Multi-Agent workflow \u5DF2\u53D6\u6D88\u3002");
+      return Date.now() - startedAt;
+    }
+    await this.channel.sendMessage(conversationId, `[CodeHarbor] Multi-Agent workflow \u5931\u8D25: ${formatError2(error)}`);
+    return Date.now() - startedAt;
+  }
   async handleStopCommand(sessionKey, message, requestId) {
     this.stateStore.deactivateSession(sessionKey);
     this.stateStore.clearCodexSessionId(sessionKey);
@@ -3619,6 +4093,25 @@ function buildFailureProgressSummary(status, startedAt, error) {
   }
   return `\u5904\u7406\u5931\u8D25\uFF08\u8017\u65F6 ${elapsed}\uFF09: ${formatError2(error)}`;
 }
+function buildWorkflowResultReply(result) {
+  return `[CodeHarbor] Multi-Agent workflow \u5B8C\u6210
+- objective: ${result.objective}
+- approved: ${result.approved ? "yes" : "no"}
+- repairRounds: ${result.repairRounds}
+- duration: ${formatDurationMs(result.durationMs)}
+
+[planner]
+${result.plan}
+[/planner]
+
+[executor]
+${result.output}
+[/executor]
+
+[reviewer]
+${result.review}
+[/reviewer]`;
+}
 
 // src/store/state-store.ts
 var import_node_fs5 = __toESM(require("fs"));
@@ -4061,6 +4554,7 @@ var CodeHarborApp = class {
       roomTriggerPolicies: config.roomTriggerPolicies,
       rateLimiterOptions: config.rateLimiter,
       cliCompat: config.cliCompat,
+      multiAgentWorkflow: config.agentWorkflow,
       configService: this.configService,
       defaultCodexWorkdir: config.codexWorkdir
     });
@@ -4185,6 +4679,8 @@ var configSchema = import_zod.z.object({
   CODEX_APPROVAL_POLICY: import_zod.z.string().optional(),
   CODEX_EXTRA_ARGS: import_zod.z.string().default(""),
   CODEX_EXTRA_ENV_JSON: import_zod.z.string().default(""),
+  AGENT_WORKFLOW_ENABLED: import_zod.z.string().default("false").transform((v) => v.toLowerCase() === "true"),
+  AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS: import_zod.z.string().default("1").transform((v) => Number.parseInt(v, 10)).pipe(import_zod.z.number().int().min(0).max(10)),
   STATE_DB_PATH: import_zod.z.string().default("data/state.db"),
   STATE_PATH: import_zod.z.string().default("data/state.json"),
   MAX_PROCESSED_EVENTS_PER_SESSION: import_zod.z.string().default("200").transform((v) => Number.parseInt(v, 10)).pipe(import_zod.z.number().int().positive()),
@@ -4234,6 +4730,10 @@ var configSchema = import_zod.z.object({
   codexApprovalPolicy: v.CODEX_APPROVAL_POLICY?.trim() || null,
   codexExtraArgs: parseExtraArgs(v.CODEX_EXTRA_ARGS),
   codexExtraEnv: parseExtraEnv(v.CODEX_EXTRA_ENV_JSON),
+  agentWorkflow: {
+    enabled: v.AGENT_WORKFLOW_ENABLED,
+    autoRepairMaxRounds: v.AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS
+  },
   stateDbPath: import_node_path7.default.resolve(v.STATE_DB_PATH),
   legacyStateJsonPath: v.STATE_PATH.trim() ? import_node_path7.default.resolve(v.STATE_PATH) : null,
   maxProcessedEventsPerSession: v.MAX_PROCESSED_EVENTS_PER_SESSION,
@@ -4382,6 +4882,8 @@ var CONFIG_SNAPSHOT_ENV_KEYS = [
   "CODEX_APPROVAL_POLICY",
   "CODEX_EXTRA_ARGS",
   "CODEX_EXTRA_ENV_JSON",
+  "AGENT_WORKFLOW_ENABLED",
+  "AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS",
   "STATE_DB_PATH",
   "STATE_PATH",
   "MAX_PROCESSED_EVENTS_PER_SESSION",
@@ -4444,6 +4946,8 @@ var envSnapshotSchema = import_zod2.z.object({
   CODEX_APPROVAL_POLICY: import_zod2.z.string(),
   CODEX_EXTRA_ARGS: import_zod2.z.string(),
   CODEX_EXTRA_ENV_JSON: jsonObjectStringSchema("CODEX_EXTRA_ENV_JSON", true),
+  AGENT_WORKFLOW_ENABLED: booleanStringSchema("AGENT_WORKFLOW_ENABLED"),
+  AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS: integerStringSchema("AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS", 0, 10),
   STATE_DB_PATH: import_zod2.z.string().min(1),
   STATE_PATH: import_zod2.z.string(),
   MAX_PROCESSED_EVENTS_PER_SESSION: integerStringSchema("MAX_PROCESSED_EVENTS_PER_SESSION", 1),
@@ -4630,6 +5134,8 @@ function buildSnapshotEnv(config) {
     CODEX_APPROVAL_POLICY: config.codexApprovalPolicy ?? "",
     CODEX_EXTRA_ARGS: config.codexExtraArgs.join(" "),
     CODEX_EXTRA_ENV_JSON: serializeJsonObject(config.codexExtraEnv),
+    AGENT_WORKFLOW_ENABLED: String(config.agentWorkflow.enabled),
+    AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS: String(config.agentWorkflow.autoRepairMaxRounds),
     STATE_DB_PATH: config.stateDbPath,
     STATE_PATH: config.legacyStateJsonPath ?? "",
     MAX_PROCESSED_EVENTS_PER_SESSION: String(config.maxProcessedEventsPerSession),
@@ -4988,7 +5494,7 @@ function buildMainServiceUnit(options) {
     "NoNewPrivileges=true",
     "PrivateTmp=true",
     "ProtectSystem=full",
-    "ProtectHome=read-only",
+    "ProtectHome=false",
     `ReadWritePaths=${runtimeHome2}`,
     "",
     "[Install]",
@@ -5016,7 +5522,7 @@ function buildAdminServiceUnit(options) {
     "NoNewPrivileges=true",
     "PrivateTmp=true",
     "ProtectSystem=full",
-    "ProtectHome=read-only",
+    "ProtectHome=false",
     `ReadWritePaths=${runtimeHome2}`,
     "",
     "[Install]",
@@ -5302,6 +5808,7 @@ configCommand.command("import").description("Import config snapshot from JSON").
 });
 serviceCommand.command("install").description("Install and enable codeharbor systemd service (requires root)").option("--run-user <user>", "service user (default: sudo user or current user)").option("--runtime-home <path>", "runtime home used as CODEHARBOR_HOME").option("--with-admin", "also install codeharbor-admin.service").option("--no-start", "enable service without starting immediately").action((options) => {
   try {
+    maybeReexecServiceCommandWithSudo();
     const runUser = options.runUser?.trim() || resolveDefaultRunUser();
     const runtimeHomePath = resolveRuntimeHomeForUser(runUser, process.env, options.runtimeHome);
     installSystemdServices({
@@ -5317,9 +5824,10 @@ serviceCommand.command("install").description("Install and enable codeharbor sys
 `);
     process.stderr.write(
       [
-        "Hint: run with sudo and absolute CLI path, for example:",
-        '  sudo "$(command -v codeharbor)" service install --with-admin',
-        "  (remove --with-admin if you only want the main service)",
+        "Hint:",
+        "  - Run directly: codeharbor service install --with-admin",
+        "  - The command auto-elevates with sudo when needed.",
+        `  - Fallback explicit form: ${buildExplicitSudoCommand("service install --with-admin")}`,
         ""
       ].join("\n")
     );
@@ -5328,6 +5836,7 @@ serviceCommand.command("install").description("Install and enable codeharbor sys
 });
 serviceCommand.command("uninstall").description("Remove codeharbor systemd service (requires root)").option("--with-admin", "also remove codeharbor-admin.service").action((options) => {
   try {
+    maybeReexecServiceCommandWithSudo();
     uninstallSystemdServices({
       removeAdmin: options.withAdmin ?? false
     });
@@ -5336,8 +5845,10 @@ serviceCommand.command("uninstall").description("Remove codeharbor systemd servi
 `);
     process.stderr.write(
       [
-        "Hint: run with sudo and absolute CLI path, for example:",
-        '  sudo "$(command -v codeharbor)" service uninstall --with-admin',
+        "Hint:",
+        "  - Run directly: codeharbor service uninstall --with-admin",
+        "  - The command auto-elevates with sudo when needed.",
+        `  - Fallback explicit form: ${buildExplicitSudoCommand("service uninstall --with-admin")}`,
         ""
       ].join("\n")
     );
@@ -5346,6 +5857,7 @@ serviceCommand.command("uninstall").description("Remove codeharbor systemd servi
 });
 serviceCommand.command("restart").description("Restart installed codeharbor systemd service (requires root)").option("--with-admin", "also restart codeharbor-admin.service").action((options) => {
   try {
+    maybeReexecServiceCommandWithSudo();
     restartSystemdServices({
       restartAdmin: options.withAdmin ?? false
     });
@@ -5354,9 +5866,10 @@ serviceCommand.command("restart").description("Restart installed codeharbor syst
 `);
     process.stderr.write(
       [
-        "Hint: run with sudo and absolute CLI path, for example:",
-        '  sudo "$(command -v codeharbor)" service restart --with-admin',
-        "  (remove --with-admin if you only want the main service)",
+        "Hint:",
+        "  - Run directly: codeharbor service restart --with-admin",
+        "  - The command auto-elevates with sudo when needed.",
+        `  - Fallback explicit form: ${buildExplicitSudoCommand("service restart --with-admin")}`,
         ""
       ].join("\n")
     );
@@ -5439,6 +5952,32 @@ function resolveCliScriptPath() {
   }
   return import_node_path12.default.resolve(__dirname, "cli.js");
 }
+function maybeReexecServiceCommandWithSudo() {
+  if (typeof process.getuid !== "function" || process.getuid() === 0) {
+    return;
+  }
+  const serviceArgs = process.argv.slice(2);
+  if (serviceArgs.length === 0 || serviceArgs[0] !== "service") {
+    return;
+  }
+  const cliScriptPath = resolveCliScriptPath();
+  const child = (0, import_node_child_process6.spawnSync)("sudo", [process.execPath, cliScriptPath, ...serviceArgs], {
+    stdio: "inherit"
+  });
+  if (child.error) {
+    throw new Error(`failed to auto-elevate with sudo: ${child.error.message}`);
+  }
+  process.exit(child.status ?? 1);
+}
+function shellQuote(value) {
+  if (!value) {
+    return "''";
+  }
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function buildExplicitSudoCommand(subcommand) {
+  return `sudo ${shellQuote(process.execPath)} ${shellQuote(resolveCliScriptPath())} ${subcommand}`;
+}
 function formatError3(error) {
   if (error instanceof Error) {
     return error.message;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeharbor",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Instant-messaging bridge for Codex CLI sessions",
   "license": "MIT",
   "main": "dist/cli.js",