@fieldwangai/agentflow 0.1.31 → 0.1.33

package/bin/lib/catalog-flows.mjs

@@ -120,10 +120,15 @@ export function listFlowsJson(workspaceRoot, opts = {}) {
 }
 
 /** 将 YAML 解析得到的 input/output 项转为 Web UI / 校验使用的槽位结构 */
+function defaultShowOnNodeForSlot(slot) {
+  const type = String(slot?.type || "").trim().toLowerCase();
+  return Boolean(slot?.required) || type === "node";
+}
+
 function normalizeFrontmatterSlots(arr) {
   if (!Array.isArray(arr)) return [];
   return arr.map((item) => {
-    if (!item || typeof item !== "object") return { type: t("catalog.type_text"), name: "", default: "" };
+    if (!item || typeof item !== "object") return { type: t("catalog.type_text"), name: "", default: "", showOnNode: false };
     const type = item.type != null ? String(item.type).trim() : t("catalog.type_text");
     const name = item.name != null ? String(item.name).trim() : "";
     let def = item.default !== undefined && item.default !== null ? item.default : item.value;
@@ -131,7 +136,7 @@ function normalizeFrontmatterSlots(arr) {
     else if (typeof def !== "string") def = String(def);
     const slot = { type, name, default: def };
     if (item.required != null) slot.required = Boolean(item.required);
-    if (item.showOnNode != null) slot.showOnNode = Boolean(item.showOnNode);
+    slot.showOnNode = item.showOnNode != null ? Boolean(item.showOnNode) : defaultShowOnNodeForSlot(slot);
     return slot;
   });
 }
@@ -656,16 +661,38 @@ function resolveMarkdownNodeFile(workspaceRoot, nodeId, flowId, flowSource, opts
 
 function readNodeUsage(workspaceRoot, nodeId, opts = {}) {
   const usage = [];
+  const marketSpec = parseMarketplaceDefinitionId(nodeId);
   for (const flow of listFlowsJson(workspaceRoot, opts)) {
     const flowPath = getFlowYamlAbs(workspaceRoot, flow.id, flow.source || "user", { archived: Boolean(flow.archived), userId: opts.userId });
     if (!flowPath.path) continue;
     try {
       const data = yaml.load(fs.readFileSync(flowPath.path, "utf-8"));
       const instances = data && typeof data === "object" ? data.instances : null;
-      if (!instances || typeof instances !== "object") continue;
-      const hits = Object.entries(instances)
-        .filter(([, inst]) => inst && inst.definitionId === nodeId)
-        .map(([instanceId, inst]) => ({ instanceId, label: inst.label || instanceId }));
+      const hits = [];
+      if (marketSpec) {
+        const deps = data && typeof data === "object" && data.dependencies && typeof data.dependencies === "object" ? data.dependencies : {};
+        const nodeDeps = Array.isArray(deps.nodes) ? deps.nodes : [];
+        if (nodeDeps.some((dep) => {
+          const parsed = typeof dep === "string"
+            ? parseMarketplaceDefinitionId(dep.startsWith("marketplace:") ? dep : `marketplace:${dep}`)
+            : dep && typeof dep === "object"
+              ? { id: dep.id, version: dep.version != null ? String(dep.version) : null }
+              : null;
+          return parsed && parsed.id === marketSpec.id && (!parsed.version || !marketSpec.version || parsed.version === marketSpec.version);
+        })) {
+          hits.push({ instanceId: "dependencies.nodes", label: "dependency" });
+        }
+      }
+      if (instances && typeof instances === "object") {
+        hits.push(...Object.entries(instances)
+          .filter(([, inst]) => {
+            if (!inst) return false;
+            if (!marketSpec) return inst.definitionId === nodeId;
+            const parsed = parseMarketplaceDefinitionId(inst.definitionId);
+            return parsed && parsed.id === marketSpec.id && (!parsed.version || !marketSpec.version || parsed.version === marketSpec.version);
+          })
+          .map(([instanceId, inst]) => ({ instanceId, label: inst.label || instanceId })));
+      }
       if (hits.length > 0) {
         usage.push({ flowId: flow.id, flowSource: flow.source || "user", archived: Boolean(flow.archived), instances: hits });
       }

package/bin/lib/composer-node-schema.mjs

@@ -114,13 +114,13 @@ export function buildNodeSchemaCompactSection() {
   lines.push("- **`node`**（控制流连线）：只表达「执行顺序」，**不携带业务数据**。串主链（Start→A→B→End）、汇合分支用它。槽位名通常是 `prev` / `next` / `prev1` / `next2` / `option_N`。⚠️ 业务字段绝不要标 `node`。");
   lines.push("- **`text`**（短上下文 / 结论 / 路径串）：上游把字符串结果（分析结论、用户输入、key 名、JSON 串）直接传给下游；下游 body / script 用 `${slotName}` 引用，apply 时原样替换。适合 < ~1KB 的内容。");
   lines.push("- **`file`**（大块产物 / 上下文文件）：上游把内容写到一个**文件**，下游通过 `${slotName}` 拿到的是**文件绝对路径**（不是内容）。下游需 Read 该路径取内容。适合报告 / todolist / 中间代码 / 截图等 > 1KB 或二进制。");
-  lines.push("- **`bool`**（仅做分支判定）：只在 `control_toBool.prediction` / `control_agent_toBool.prediction`(out) → `control_if.prediction`(in) 一对位置使用，其它任何节点禁止 `bool` 槽。");
+  lines.push("- **`bool`**（仅做分支判定）：由 `provide_bool.value` / `control_toBool.prediction` / `control_agent_toBool.prediction` 输出，接到 `control_if.prediction` 输入；其它业务节点不要新增 `bool` 槽。");
   lines.push("");
   lines.push("**选 type 决策**：");
   lines.push("- 想表达「下一步走谁」 → `node`");
   lines.push("- 想传「短串/路径/key/JSON」 → `text`");
   lines.push("- 想传「整篇文档/报告/JSON 文件/代码」 → `file`");
-  lines.push("- 想做「if 真假分支」 → `control_toBool`（确定性）或 `control_agent_toBool`（AI 判断）→ `control_if`（用 bool 引脚）");
+  lines.push("- 想做「if 真假分支」 → 手动开关用 `provide_bool`，确定性判断用 `control_toBool`，AI 判断用 `control_agent_toBool`，再接 `control_if` 的 bool 引脚");
   lines.push("");
   lines.push("## 内置节点 schema（权威，必须严格遵守）");
   lines.push(
@@ -136,7 +136,7 @@ export function buildNodeSchemaCompactSection() {
   lines.push("**硬性约束（违反则 validate-flow 失败）：**");
   lines.push("1. **固定槽位节点**（未带 ★）：`input`/`output` 数组必须**完整复制**上表槽位（`type`、`name`、顺序、个数均不可改），仅可填写 `value`。");
   lines.push("2. **可扩展节点**（带 ★）：基础骨架不可删改，可在数组**末尾追加** type=`text` 或 `file` 的业务数据槽（按上方语义选 text 还是 file）。⚠️ 业务槽 type 必须 `text` 或 `file`，**绝对不能写 `node`**（node 仅控制流）。");
-  lines.push("3. `provide_*` 节点不得连入控制链（node→node 边），仅作数据源向下游 text/file 槽供值。");
+  lines.push("3. `provide_*` 节点不得连入控制链（node→node 边），仅作数据源向下游 text/file/bool 槽供值。");
   lines.push("4. 边连接时 `sourceHandle: output-N` 与 `targetHandle: input-N` 的索引必须对应**同一 type**；type 不一致禁止连线（text 不能接 file，node 不能接 text）。");
   lines.push("5. **YAML 多行字符串必须用 `|` 块标量。** 写 `script` / `body` / `value` 等字符串字段时，只要内容含 `: `、`\"`、`'`、`#`、换行、shell 操作符，**强制**使用 `|` 块。");
   cachedCompact = lines.join("\n");
@@ -157,7 +157,7 @@ export function buildNodeSchemaPromptSection() {
   lines.push("- **`node`**（控制流连线）：只表达「执行顺序」，**不携带业务数据**。串主链、汇合分支用它。槽位名通常是 `prev` / `next` / `prev1` / `next2` / `option_N`。⚠️ 业务字段绝不要标 `node`。");
   lines.push("- **`text`**（短上下文 / 结论 / 路径串）：上游把字符串结果（分析结论、用户输入、key 名、JSON 串）直接传给下游；下游 body / script 用 `${slotName}` 引用，apply 时原样替换。适合 < ~1KB 的内容。");
   lines.push("- **`file`**（大块产物 / 上下文文件）：上游把内容写到一个**文件**，下游通过 `${slotName}` 拿到的是**文件绝对路径**（不是内容）。下游需 Read 该路径取内容。适合报告 / todolist / 中间代码 / 截图等 > 1KB 或二进制。");
-  lines.push("- **`bool`**（仅做分支判定）：只在 `control_toBool.prediction` / `control_agent_toBool.prediction`(out) → `control_if.prediction`(in) 一对位置使用，其它任何节点禁止 `bool` 槽。");
+  lines.push("- **`bool`**（仅做分支判定）：由 `provide_bool.value` / `control_toBool.prediction` / `control_agent_toBool.prediction` 输出，接到 `control_if.prediction` 输入；其它业务节点不要新增 `bool` 槽。");
   lines.push("");
   lines.push("## 内置节点 schema（权威，必须严格遵守）");
   lines.push(
@@ -177,7 +177,7 @@ export function buildNodeSchemaPromptSection() {
   lines.push(
     "2. **可扩展节点**（带 ★：agent_subAgent / tool_nodejs / tool_user_check）：" +
     "上表槽位为**基础骨架不可删改**（`prev`/`next` 等控制槽与 schema 已有数据槽的 `type`/`name`/顺序保持一致）；" +
-    "可在数组**末尾追加** type=`text` 或 `file` 的业务数据槽（`bool` 仅 control_toBool / control_agent_toBool / control_if 使用，禁止他处出现），" +
+    "可在数组**末尾追加** type=`text` 或 `file` 的业务数据槽（`bool` 仅 provide_bool / control_toBool / control_agent_toBool / control_if 使用，禁止他处出现），" +
     "命名应与上下游语义对齐（如 `fromapp`、`analysis`、`compile_result`、`result`），便于阶段三连线。"
   );
   lines.push(
@@ -186,7 +186,7 @@ export function buildNodeSchemaPromptSection() {
     " 不要因为 schema 表里 `prev:node` 就惯性给 `fromapp`/`toapp`/`page_name` 也写 `node`——那意味着「控制流连线」，下游会报「边类型不一致」。"
   );
   lines.push(
-    "3. `provide_*` 节点不得连入控制链（node→node 边），仅作数据源向下游 text/file 槽供值。"
+    "3. `provide_*` 节点不得连入控制链（node→node 边），仅作数据源向下游 text/file/bool 槽供值。"
   );
   lines.push(
     "4. 边连接时 `sourceHandle: output-N` 与 `targetHandle: input-N` 的索引必须对应同一 type；type 不一致禁止连线。"
@@ -214,7 +214,7 @@ export function buildNodeSchemaPromptSection() {
   lines.push("│    └─ type: text   ✅");
   lines.push("├─ 文件绝对路径（todolist.json、conversion_result.md、screenshot.png …）");
   lines.push("│    └─ type: file   ✅");
-  lines.push("└─ 二元判定值（仅 control_toBool / control_agent_toBool 的 prediction、control_if 的 prediction）");
+  lines.push("└─ 二元判定值（provide_bool.value、control_toBool / control_agent_toBool 的 prediction、control_if 的 prediction）");
   lines.push("     └─ type: bool   ✅（其他节点禁用）");
   lines.push("");
   lines.push("⛔ 任何业务数据槽都**不可**写 type: node");

package/bin/lib/composer-planner.mjs

@@ -123,7 +123,7 @@ function buildPhasedSystemPrompt(phaseName, intents) {
 为**每个**需要完善的 instance 生成独立 agent 步骤（或确定性 script 步骤）：
 - **agent_subAgent**：若 body 已是可执行 prompt 则跳过；否则编写**准确、可执行**的 \`body\`（提示词/规则/输入输出占位 \`\${...}\`）。**复杂度用 "simple"**。
 - **tool_nodejs**：若 \`script\` 字段已是完整命令且 scripts/ 下脚本已存在 → 跳过；否则在 **scripts/** 子目录创建 Node 脚本（\`scripts/<instanceId>.mjs\`），\`script\` 写入完整 \`node ...\` 调用并用 \`\${}\` 引用槽位。**引用 scripts/ 必须用 \`\${flowDir}/scripts/xxx.mjs\`**，不要写 \`\${workspaceRoot}/.workspace/agentflow/pipelines/\${flowName}/scripts/...\`（flow 可能安装到 \`~/agentflow/pipelines\` 或 builtin，硬编码 workspace 路径会找不到脚本）。**不要**给 \`\${workspaceRoot}\`、\`\${runDir}\` 等外包双引号（已自动 shell-quote）。**禁止**仅 body 自然语言无 script。
-- **control_toBool / provide_str / provide_file** 等：按规格书补齐空的 \`body\` 或 output \`value\`。
+- **control_toBool / provide_str / provide_file / provide_bool** 等：按规格书补齐空的 \`body\` 或 output \`value\`。
 - **引脚补漏**：核对 body/script 中每个 \`\${X}\` 是否对应实际槽位 name；缺槽就在末尾追加（type 必为 \`text\` 或 \`file\`，**绝不写 node**），多余的不要动（可能是阶段三连线用）。
 - **不得删改基础控制槽**（\`prev\`/\`next\` 的 type/name 与顺序）；**固定槽位节点**（control_* / provide_* / tool_load_key/save_key/get_env / tool_print / tool_user_ask）的 input/output 结构永不修改。
 
@@ -146,9 +146,9 @@ function buildPhasedSystemPrompt(phaseName, intents) {
 2. **引脚语义审查 checklist**（每节点过一遍，发现问题修正）：
    a. **同 output 多消费者冲突**：一个 output 槽被两条边消费且消费方语义矛盾（如同时供 \`control_toBool.value\`（要 true/false 单行）和 \`agent.input\`（要详细内容）→ 必须**拆成两个 output 槽**（如 \`result:text\` + \`report:file\`）
    b. **text vs file 错配**：内容超过 ~1KB 或为多行报告/日志/源码 → 应是 \`file\`；只是路径串/key/JSON 短串 → 应是 \`text\`
-   c. **bool 误用**：\`bool\` 槽只允许出现在 \`control_toBool.prediction\` / \`control_agent_toBool.prediction\`(out) 与 \`control_if.prediction\`(in) 这一对位置，其它任何节点禁用
+   c. **bool 误用**：\`bool\` 槽只允许出现在 \`provide_bool.value\`、\`control_toBool.prediction\` / \`control_agent_toBool.prediction\`(out) 与 \`control_if.prediction\`(in)，其它任何节点禁用
    d. **节点类型错配**：发现 \`tool_nodejs\` 实际做的是非确定性任务（代码翻译/源码理解/创意生成）→ 改 \`definitionId: agent_subAgent\` + 删 script + 把要求写到 body
-   e. **provide_* 类型对齐**：\`provide_str\` 必须 \`output[0].type=text\`；\`provide_file\` 必须 \`output[0].type=file\`
+   e. **provide_* 类型对齐**：\`provide_str\` 必须 \`output[0].type=text\`；\`provide_file\` 必须 \`output[0].type=file\`；\`provide_bool\` 必须 \`output[0].type=bool\`
 3. **ui.nodePositions**：按 \`reference/flow-layout.md\` 优化布局（主链 x 递增、分支 y 错开、避免一条线）。
 4. 完成后应能通过 validate-flow；可用 add-edge、update-position 等 script 步骤，必要时用 agent 步骤处理复杂拓扑。
 
@@ -648,9 +648,9 @@ function buildPhaseCliGuide(phaseIndex) {
 2. **引脚语义审查 checklist**（每节点过一遍）：
    a. **同 output 多消费者冲突**：一个 output 同时供给两个语义矛盾的下游（如 \`toBool.value\` 要单行 true/false 与 \`agent.input\` 要详细内容）→ 拆成两个 output 槽
    b. **text/file 错配**：内容超 ~1KB 或多行报告/源码 → 应是 \`file\`；只是路径串/key/JSON 短串 → 应是 \`text\`
-   c. **bool 误用**：\`bool\` 槽只允许 \`control_toBool.prediction\` / \`control_agent_toBool.prediction\`(out) → \`control_if.prediction\`(in)，其它禁用
+   c. **bool 误用**：\`bool\` 槽只允许 \`provide_bool.value\`、\`control_toBool.prediction\` / \`control_agent_toBool.prediction\`(out) → \`control_if.prediction\`(in)，其它禁用
    d. **节点类型错配**：\`tool_nodejs\` 实际做非确定性任务（代码翻译/源码理解/创意生成）→ 改 \`definitionId: agent_subAgent\` + 删 script + 写 body
-   e. **provide_* 类型对齐**：\`provide_str.output[0].type\` 必为 \`text\`；\`provide_file.output[0].type\` 必为 \`file\`
+   e. **provide_* 类型对齐**：\`provide_str.output[0].type\` 必为 \`text\`；\`provide_file.output[0].type\` 必为 \`file\`；\`provide_bool.output[0].type\` 必为 \`bool\`
 3. **优化 ui.nodePositions**（参考 flow-layout.md：主链 x 递增、分支 y 错开）。
 4. 完成后须能通过 **validate-flow**；本轮结束后系统会自动校验并尝试修复。`;
   }

package/bin/lib/git-worktree.mjs

@@ -0,0 +1,248 @@
+import fs from "fs";
+import path from "path";
+import { spawnSync } from "child_process";
+
+export function runGit(args, cwd) {
+  return spawnSync("git", args, {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function parseJsonObject(raw) {
+  if (raw == null) return null;
+  if (typeof raw === "object" && !Array.isArray(raw)) return raw;
+  const text = String(raw || "").trim();
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function gitOrThrow(args, cwd, label) {
+  const result = runGit(args, cwd);
+  if (result.status !== 0) {
+    throw new Error(`${label || "git"} failed: ${result.stderr || result.stdout || result.error?.message || "unknown error"}`);
+  }
+  return result.stdout.trim();
+}
+
+function readGitRemoteUrl(repoPath, remote = "origin") {
+  const result = runGit(["remote", "get-url", remote], repoPath);
+  return result.status === 0 ? result.stdout.trim() : "";
+}
+
+function parseRemoteUrl(remoteUrl) {
+  const raw = String(remoteUrl || "").trim().replace(/\.git$/i, "");
+  if (!raw) return { host: "", projectPath: "", provider: "" };
+  let host = "";
+  let projectPath = "";
+  const scpLike = raw.match(/^[^@]+@([^:]+):(.+)$/);
+  if (scpLike) {
+    host = scpLike[1];
+    projectPath = scpLike[2].replace(/^\/+/, "");
+  } else {
+    try {
+      const u = new URL(raw);
+      host = u.host;
+      projectPath = u.pathname.replace(/^\/+/, "");
+    } catch {
+      projectPath = raw;
+    }
+  }
+  const provider = host && /gitlab|git\.sysop/i.test(host) ? "gitlab" : "";
+  return { host, projectPath, provider };
+}
+
+export function normalizeGitContext(raw) {
+  const parsed = parseJsonObject(raw);
+  if (!parsed) return null;
+  return {
+    version: 1,
+    repoPath: parsed.repoPath ? path.resolve(String(parsed.repoPath)) : "",
+    worktreePath: parsed.worktreePath ? path.resolve(String(parsed.worktreePath)) : "",
+    branch: parsed.branch ? String(parsed.branch) : "",
+    commit: parsed.commit ? String(parsed.commit) : "",
+    remote: parsed.remote ? String(parsed.remote) : "",
+    remoteUrl: parsed.remoteUrl ? String(parsed.remoteUrl) : "",
+    provider: parsed.provider ? String(parsed.provider) : "",
+    host: parsed.host ? String(parsed.host) : "",
+    projectPath: parsed.projectPath ? String(parsed.projectPath) : "",
+  };
+}
+
+export function buildGitContext({ repoPath, worktreePath = "", branch = "", commit = "", remote = "origin", remoteUrl = "" }) {
+  const repoRoot = resolveGitRepoRoot(repoPath);
+  const actualRemote = String(remote || "origin").trim() || "origin";
+  const actualRemoteUrl = remoteUrl || readGitRemoteUrl(repoRoot, actualRemote);
+  const remoteMeta = parseRemoteUrl(actualRemoteUrl);
+  return {
+    version: 1,
+    repoPath: repoRoot,
+    worktreePath: worktreePath ? path.resolve(worktreePath) : "",
+    branch: String(branch || ""),
+    commit: String(commit || ""),
+    remote: actualRemote,
+    remoteUrl: actualRemoteUrl,
+    provider: remoteMeta.provider,
+    host: remoteMeta.host,
+    projectPath: remoteMeta.projectPath,
+  };
+}
+
+export function sanitizeWorktreeName(raw) {
+  return String(raw || "worktree")
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    || "worktree";
+}
+
+export function resolveGitRepoRoot(repoPath) {
+  const raw = String(repoPath || "").trim();
+  if (!raw) throw new Error("repoPath is required");
+  const abs = path.resolve(raw);
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) {
+    throw new Error(`repoPath directory not found: ${abs}`);
+  }
+  return path.resolve(gitOrThrow(["rev-parse", "--show-toplevel"], abs, "git rev-parse"));
+}
+
+export function currentGitBranch(repoRoot) {
+  const branch = gitOrThrow(["rev-parse", "--abbrev-ref", "HEAD"], repoRoot, "git rev-parse branch");
+  return branch === "HEAD" ? "" : branch;
+}
+
+export function currentGitCommit(repoRoot) {
+  return gitOrThrow(["rev-parse", "HEAD"], repoRoot, "git rev-parse commit");
+}
+
+export function listGitWorktrees(repoRoot) {
+  const text = gitOrThrow(["worktree", "list", "--porcelain"], repoRoot, "git worktree list");
+  const entries = [];
+  let current = null;
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim()) {
+      if (current) entries.push(current);
+      current = null;
+      continue;
+    }
+    const [key, ...rest] = line.split(" ");
+    const value = rest.join(" ").trim();
+    if (key === "worktree") {
+      if (current) entries.push(current);
+      current = { path: path.resolve(value), head: "", branchRef: "", branch: "" };
+    } else if (current && key === "HEAD") {
+      current.head = value;
+    } else if (current && key === "branch") {
+      current.branchRef = value;
+      current.branch = value.replace(/^refs\/heads\//, "");
+    } else if (current && key === "detached") {
+      current.branch = "DETACHED";
+    }
+  }
+  if (current) entries.push(current);
+  return entries;
+}
+
+export function findRegisteredWorktree(repoRoot, worktreePath) {
+  const target = path.resolve(worktreePath);
+  return listGitWorktrees(repoRoot).find((entry) => path.resolve(entry.path) === target) || null;
+}
+
+function branchExists(repoRoot, branch) {
+  const result = runGit(["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], repoRoot);
+  return result.status === 0;
+}
+
+function defaultWorktreePath(pipelineWorkspace, repoRoot, branch) {
+  const repoName = sanitizeWorktreeName(path.basename(repoRoot));
+  const commit = currentGitCommit(repoRoot);
+  const currentBranch = currentGitBranch(repoRoot);
+  const refLabel = branch || currentBranch || commit.slice(0, 12);
+  return path.join(path.resolve(pipelineWorkspace), ".workspace", "agentflow", "worktrees", repoName, sanitizeWorktreeName(refLabel));
+}
+
+function actualWorktreeBranch(worktreePath) {
+  const branch = gitOrThrow(["rev-parse", "--abbrev-ref", "HEAD"], worktreePath, "git rev-parse worktree branch");
+  return branch === "HEAD" ? "DETACHED" : branch;
+}
+
+export function loadGitWorktree({ repoPath, branch = "", worktreePath = "", pipelineWorkspace }) {
+  const repoRoot = resolveGitRepoRoot(repoPath);
+  const wantedBranch = String(branch || "").trim();
+  const target = path.resolve(worktreePath || defaultWorktreePath(pipelineWorkspace || repoRoot, repoRoot, wantedBranch));
+
+  if (wantedBranch && !branchExists(repoRoot, wantedBranch)) {
+    throw new Error(`branch does not exist in repoPath: ${wantedBranch}`);
+  }
+
+  const registered = findRegisteredWorktree(repoRoot, target);
+  if (fs.existsSync(target)) {
+    if (!registered) {
+      throw new Error(`worktreePath exists but is not registered for repoPath: ${target}`);
+    }
+    if (wantedBranch && registered.branch !== wantedBranch) {
+      throw new Error(`worktreePath branch mismatch: expected ${wantedBranch}, got ${registered.branch || "DETACHED"}`);
+    }
+  } else {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const args = wantedBranch
+      ? ["worktree", "add", target, wantedBranch]
+      : ["worktree", "add", "--detach", target, "HEAD"];
+    const result = runGit(args, repoRoot);
+    if (result.status !== 0) {
+      throw new Error(`git worktree add failed: ${result.stderr || result.stdout}`);
+    }
+  }
+
+  const actualBranch = actualWorktreeBranch(target);
+  const commit = currentGitCommit(target);
+  return {
+    repoRoot,
+    worktreePath: target,
+    branch: actualBranch,
+    commit,
+  };
+}
+
+export function unloadGitWorktree({ repoPath, worktreePath, force = false, prune = true }) {
+  const repoRoot = resolveGitRepoRoot(repoPath);
+  const targetRaw = String(worktreePath || "").trim();
+  if (!targetRaw) throw new Error("worktreePath is required");
+  const target = path.resolve(targetRaw);
+  const registered = findRegisteredWorktree(repoRoot, target);
+  if (!registered) {
+    throw new Error(`worktreePath is not registered for repoPath: ${target}`);
+  }
+
+  if (!force && fs.existsSync(target)) {
+    const status = runGit(["status", "--porcelain"], target);
+    if (status.status !== 0) throw new Error(`git status failed: ${status.stderr || status.stdout}`);
+    if (status.stdout.trim()) {
+      throw new Error("worktree has uncommitted or untracked changes; set force=true to remove it");
+    }
+  }
+
+  const args = ["worktree", "remove"];
+  if (force) args.push("--force");
+  args.push(target);
+  const remove = runGit(args, repoRoot);
+  if (remove.status !== 0) {
+    throw new Error(`git worktree remove failed: ${remove.stderr || remove.stdout}`);
+  }
+  if (prune) {
+    const pruneResult = runGit(["worktree", "prune"], repoRoot);
+    if (pruneResult.status !== 0) throw new Error(`git worktree prune failed: ${pruneResult.stderr || pruneResult.stdout}`);
+  }
+  return {
+    repoRoot,
+    worktreePath: target,
+    removed: true,
+    message: `removed worktree: ${target}`,
+  };
+}

package/bin/lib/gitlab-mr.mjs

@@ -0,0 +1,174 @@
+import path from "path";
+
+import { buildGitContext, currentGitBranch, currentGitCommit, normalizeGitContext, resolveGitRepoRoot, runGit } from "./git-worktree.mjs";
+
+function gitOrThrow(args, cwd, label) {
+  const result = runGit(args, cwd);
+  if (result.status !== 0) {
+    throw new Error(`${label || "git"} failed: ${result.stderr || result.stdout || result.error?.message || "unknown error"}`);
+  }
+  return result.stdout.trim();
+}
+
+function isTruthy(value, defaultValue = false) {
+  const text = String(value ?? "").trim().toLowerCase();
+  if (!text) return Boolean(defaultValue);
+  return text === "true" || text === "1" || text === "yes" || text === "y" || text === "on";
+}
+
+function resolveToken(env, tokenEnv) {
+  const names = String(tokenEnv || "")
+    .split(/[\s,]+/)
+    .map((name) => name.trim())
+    .filter(Boolean);
+  const candidates = names.length > 0 ? names : ["GITLAB_TOKEN", "GITLAB_PRIVATE_TOKEN"];
+  for (const name of candidates) {
+    const value = env?.[name];
+    if (value != null && String(value).trim()) return { token: String(value), tokenEnv: name };
+  }
+  throw new Error(`GitLab token not found in env: ${candidates.join(", ")}`);
+}
+
+function apiBaseFromContext(gitContext, explicit) {
+  const raw = String(explicit || "").trim().replace(/\/+$/, "");
+  if (raw) return raw.endsWith("/api/v4") ? raw : `${raw}/api/v4`;
+  const host = String(gitContext?.host || "").trim();
+  if (!host) throw new Error("gitlabApiBase or gitContext.host is required");
+  return `https://${host}/api/v4`;
+}
+
+function projectPathFromContext(gitContext) {
+  const projectPath = String(gitContext?.projectPath || "").trim().replace(/^\/+|\/+$/g, "");
+  if (!projectPath) throw new Error("gitContext.projectPath is required");
+  return projectPath;
+}
+
+function encodeProject(projectPath) {
+  return encodeURIComponent(projectPath);
+}
+
+async function gitlabJson(url, options = {}) {
+  const res = await fetch(url, options);
+  const text = await res.text();
+  let json = null;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = null;
+  }
+  if (!res.ok) {
+    const message = json?.message ? JSON.stringify(json.message) : text || `HTTP ${res.status}`;
+    throw new Error(`GitLab API failed: ${message}`);
+  }
+  return json;
+}
+
+function latestCommitSubject(repoPath) {
+  return gitOrThrow(["log", "-1", "--pretty=%s"], repoPath, "git log subject") || "";
+}
+
+function recentCommitDescription(repoPath, targetBranch, sourceBranch) {
+  const ranges = [
+    [`origin/${targetBranch}..${sourceBranch}`],
+    [`${targetBranch}..${sourceBranch}`],
+    ["-5"],
+  ];
+  for (const range of ranges) {
+    const result = runGit(["log", "--pretty=format:- %h %s", ...range], repoPath);
+    if (result.status === 0 && result.stdout.trim()) return result.stdout.trim();
+  }
+  return "";
+}
+
+function normalizeLabels(labels) {
+  return String(labels || "")
+    .split(",")
+    .map((label) => label.trim())
+    .filter(Boolean)
+    .join(",");
+}
+
+export async function createGitLabMergeRequest(payload = {}, env = process.env) {
+  const inputGitContext = normalizeGitContext(payload.gitContext);
+  const repoCandidate = String(payload.repoPath || "").trim() ||
+    inputGitContext?.worktreePath ||
+    inputGitContext?.repoPath ||
+    String(payload.workspaceCwd || "").trim();
+  if (!repoCandidate) throw new Error("repoPath, gitContext, or workspaceContext cwd is required");
+  const repoPath = resolveGitRepoRoot(repoCandidate);
+  const remote = String(payload.remote || inputGitContext?.remote || "origin").trim() || "origin";
+  const commit = currentGitCommit(repoPath);
+  const gitContext = inputGitContext?.projectPath
+    ? { ...inputGitContext, commit: inputGitContext.commit || commit, remote }
+    : buildGitContext({ repoPath, branch: currentGitBranch(repoPath) || "DETACHED", commit, remote });
+  const sourceBranch = String(payload.sourceBranch || gitContext.branch || currentGitBranch(repoPath) || "").trim();
+  if (!sourceBranch || sourceBranch === "DETACHED") {
+    throw new Error("sourceBranch is required when repository is in detached HEAD");
+  }
+  const targetBranch = String(payload.targetBranch || "main").trim() || "main";
+  const title = String(payload.title || "").trim() || latestCommitSubject(repoPath) || `${sourceBranch} -> ${targetBranch}`;
+  const description = String(payload.description || "").trim() || recentCommitDescription(repoPath, targetBranch, sourceBranch);
+  const apiBase = apiBaseFromContext(gitContext, payload.gitlabApiBase);
+  const projectPath = projectPathFromContext(gitContext);
+  const { token, tokenEnv } = resolveToken(env, payload.tokenEnv);
+  const headers = {
+    "PRIVATE-TOKEN": token,
+    "Content-Type": "application/json",
+  };
+
+  if (isTruthy(payload.push, true)) {
+    const push = runGit(["push", "-u", remote, sourceBranch], repoPath);
+    if (push.status !== 0) throw new Error(`git push failed: ${push.stderr || push.stdout}`);
+  }
+
+  const query = new URLSearchParams({
+    state: "opened",
+    source_branch: sourceBranch,
+    target_branch: targetBranch,
+  });
+  const projectId = encodeProject(projectPath);
+  const existing = await gitlabJson(`${apiBase}/projects/${projectId}/merge_requests?${query.toString()}`, { headers });
+  const openMr = Array.isArray(existing) ? existing[0] : null;
+  if (openMr?.web_url) {
+    return {
+      created: false,
+      mrUrl: openMr.web_url,
+      mrIid: openMr.iid,
+      projectId: openMr.project_id,
+      sourceBranch,
+      targetBranch,
+      title: openMr.title || title,
+      message: `reused existing MR: ${openMr.web_url}`,
+      tokenEnv,
+    };
+  }
+
+  const body = {
+    source_branch: sourceBranch,
+    target_branch: targetBranch,
+    title: isTruthy(payload.draft, false) && !/^draft:/i.test(title) ? `Draft: ${title}` : title,
+    description,
+    remove_source_branch: isTruthy(payload.removeSourceBranch, false),
+    squash: isTruthy(payload.squash, false),
+  };
+  const labels = normalizeLabels(payload.labels);
+  if (labels) body.labels = labels;
+
+  const created = await gitlabJson(`${apiBase}/projects/${projectId}/merge_requests`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+  if (!created?.web_url) throw new Error("GitLab API did not return merge request URL");
+  return {
+    created: true,
+    mrUrl: created.web_url,
+    mrIid: created.iid,
+    projectId: created.project_id,
+    sourceBranch,
+    targetBranch,
+    title: created.title || body.title,
+    message: `created MR: ${created.web_url}`,
+    tokenEnv,
+  };
+}

package/bin/lib/locales/en.json

@@ -281,6 +281,18 @@
       "displayName": "Git Checkout",
       "description": "Clone or update a Git repository and expose it as a workspace context"
     },
+    "tool_git_worktree_load": {
+      "displayName": "Load Worktree",
+      "description": "Create or reuse a Git worktree and output workspaceContext and gitContext"
+    },
+    "tool_git_worktree_unload": {
+      "displayName": "Unload Worktree",
+      "description": "Remove a Git worktree and restore downstream workspace context"
+    },
+    "tool_gitlab_create_mr": {
+      "displayName": "Create GitLab MR",
+      "description": "Create or reuse a GitLab merge request for the current branch and output its URL"
+    },
     "tool_nodejs": {
       "displayName": "Node.js Script",
       "description": "Execute Node.js script, success determined by exit code, stdout as result"
@@ -313,6 +325,14 @@
       "displayName": "ASCII Display",
       "description": "Render ASCII diagram text on the Workspace canvas and pass the text downstream"
     },
+    "display_html": {
+      "displayName": "HTML Display",
+      "description": "Render HTML in a sandboxed iframe on the Workspace canvas and pass the source downstream"
+    },
+    "display_image": {
+      "displayName": "Image Display",
+      "description": "Preview an image URL, data URL, or image path on the Workspace canvas and pass the source downstream"
+    },
     "provide_str": {
       "displayName": "Text",
       "description": "Provide a text value directly, value will be passed to downstream as-is"
@@ -320,6 +340,10 @@
     "provide_file": {
       "displayName": "File",
       "description": "Provide file path or content directly, value will be passed to downstream as-is"
+    },
+    "provide_bool": {
+      "displayName": "Boolean",
+      "description": "Provide a true/false boolean value directly to downstream bool pins"
     }
   },
   "pipeline": {