langflower 0.1.1 → 0.1.3

package/README.md

@@ -3,125 +3,83 @@
 > **Disclaimer:** Langflower is currently in internal testing. Anyone can
 > download and try it, but some functions may not be stable.
 
-## Key concept: everything is a node
-
-Langflower is not built around the LLM as a first-class citizen. The core
-abstraction is a **reactive node**: several typed inputs, several typed
-outputs. Each port acts independently — a node can receive on one input
-and emit on one output at any time, without waiting for the rest. The
-runtime wires those nodes into a workflow.
-
-That is enough for complex processing chains — including loops and
-conditions.
-
-The trick is the same rule applied to models. Because ports fire on their
-own, an LLM agent is just another reactive node: prompt and tools in;
-response out; streaming tool log, reasoning, and draft as extra outputs
-that can update while the run continues. All LLM-specific logic stays as
-that node's internal state. It does not leak through the rest of the app.
-
-## Open possibilities
-
-Because every unit of work is a node, Langflower is not pinned to one
-product shape — coding harness, chat harness, or any other fixed loop.
-Workflows stay flexible. With the right wiring they fit the job.
-
-Need a chat? Wire user input, an agent, and HITL feedback. Agent-to-agent
-dialogue is two agents connected together. Coding is the same graph plus
-file-ops tools. Tired of “I’m done” while the code still does not compile?
-Write a custom review-gate node. The agent never gets a path around it.
-
-## Hard harness
-
-The sequence is the workflow topology. That is how Langflower orchestrates
-complex work: QA, review, and code checks sit on the graph, so agents
-cannot skip them. A well-configured workflow forces high-quality output —
-the model does not get to declare itself finished.
+Langflower is a local visual workflow for a project folder: a node graph
+that runs agents, tools, checks, and human gates on your machine. You
+author the pipeline on a canvas in the browser you already have. The LLM
+is a node in that graph, not the product — the topology you wire decides
+what happens next. Data, custom nodes, and workflows stay in that folder.
 
 **Not another chat harness. A local node graph.**
 
-### Keep everything local
-
-Langflower runs on your machine and does not expose your project as a
-hosted product. Files stay where they are. You can reproduce what mature
-cloud tools offer — at home, or on a closed network with internal LLM
-providers.
-
-### Scoped to a folder
-
-You start from a folder. Data, custom nodes, and workflows are scoped to
-that workspace. Open the folder, and the graph, files, and run belong
-together.
-
-### Extensible even now
-
-This is still an early version, but Langflower already supports custom
-nodes and custom node packs. Share and reuse workflows and nodes the same
-way you share the rest of the project.
+The unit of work is a **reactive node**: typed inputs, typed outputs.
+Each port fires on its own — a node can emit on one output without
+waiting for the rest, so the node chooses the path. That is enough for
+cycles and conditional branches, not only a straight chain. An LLM agent
+is the same kind of node — prompt and tools in, response out. Coding,
+chat, agent-to-agent dialogue, and custom gates are the same idea: pick
+the graph, not a fixed loop.
 
 ![Langflower starter workflow](https://raw.githubusercontent.com/earthdmitriy/langflower/master/docs/img/starter.png)
 
-## How it works
+The default **starter** workflow: an onboarding helper plus a Writer
+sub-agent for workflows and custom nodes.
 
-1. Start Langflower with a project folder.
-2. Open a workflow on the canvas, or create one for the task.
-3. Run it and watch agents, tools, checks, and file changes move through
-   visible stages.
-4. Approve, reject, or add feedback when the workflow asks for a human
-   decision.
-5. Find the resulting files and data in the same workspace.
-
-## Under the hood
-
-The core is a reactive runtime that wires nodes together. The **node SDK**
-is the public contract: any node that follows it can run on that runtime.
-**Common nodes** is the built-in catalog. It uses the same SDK as custom
-node packs.
+![Langflower dev workflow](https://raw.githubusercontent.com/earthdmitriy/langflower/master/docs/img/lf_dev.png)
 
-The **server** composes those pieces, compiles user-defined nodes, and owns
-the live run. The **UI** is a thin browser client. It listens to WebSocket
-events from the server; it does not own the workflow. Close the tab while a
-long run continues. Reopen it, and the server catches the UI up, so the
-canvas stays in sync.
-
-For a short builder-oriented picture, see
-[How it works](https://github.com/earthdmitriy/langflower/blob/master/docs/public/how-it-works.md).
+**Langflower dev** — the workflow used to develop Langflower itself.
+Memory tools, ts-scan (MCP), and custom **LF Dev Tools** merge in a tool
+collection and fan out to the agents. The prompt passes **lf-review-gate**
+first (format, typecheck, tests) so Plan starts from a green tree. A
+human review gate accepts the plan, then Coder works; the result must
+pass lf-review-gate again, then a human review gate.
 
 ## Why Langflower
 
-- **You stay in control.** Workflows can request approval before sensitive
-  file edits or shell commands run.
-- **Use the browser you already have.** Other harnesses pack a web UI into
-  a built-in browser such as Electron. Langflower uses your existing
-  browser, so you can close the tab, free those resources, and let the
-  server keep the run; reopen it and the UI catches up.
-- **Extend it when the defaults are not enough.** Langflower uses common
-  agent primitives — **MCP** and **skills** — and lets you define **custom
-  nodes** on top: processing in the graph, or custom tools for agents via
-  the same **ToolHandle** contract as built-ins.
+- **The graph is the harness.** QA, review, build, and tests sit on the
+  topology, so the agent cannot skip them or declare itself finished. A
+  review-gate has no path around it.
+- **Safe tools, not a general shell.** Wrap format, build, and unit tests
+  as custom nodes that expose a **ToolHandle**. You do not need a general
+  bash tool that could accidentally wipe all data from your disk. If a
+  command must stay open-ended, the workflow can still ask for approval
+  first.
+- **Your browser, not a bundled one.** Close the tab and free those
+  resources; the server keeps the run. Reopen it, and the UI catches up.
+
+Versus chat-style harnesses (OpenCode-like): order comes from the graph,
+not from the model deciding it is done. Versus cloud graph tools
+(Langflow, n8n): the same idea of wiring nodes, aimed at a folder on
+your machine — home or a closed network with internal providers — not at
+hosting a service.
+
+**MCP** and **skills** work as usual. Custom nodes sit on top of the same
+**ToolHandle** contract as built-ins.
 
-## How it compares
+## Quick start
 
-Versus chat-style harnesses (often an Electron shell around a model loop):
-Langflower is a local node graph. The LLM is a node, not the product.
-Order comes from topology, not from the model deciding it is done.
-The UI is your existing browser, not a bundled one.
+If you do not want to bother with a terminal, use the **desktop
+launcher**. Pick a project folder, click **Start**, and the editor opens
+in the browser you already have. Several folders can run at once, each
+on its own port. The launcher takes care of missing Node.js and
+Langflower, and checks for Langflower updates for you. It does not
+update itself — download a newer zip when you want a new window.
 
-Versus cloud graph tools: the same idea of wiring nodes, but aimed at a
-folder on your machine — home or a closed network with internal
-providers — not at hosting a service or cloning ETL in the cloud.
+![Langflower desktop launcher](https://raw.githubusercontent.com/earthdmitriy/langflower/master/docs/img/launcher.png)
 
-## What it lacks
+Download a Windows or macOS zip from
+[GitHub Releases](https://github.com/earthdmitriy/langflower/releases).
+Unpack and run `langflower-launcher.exe` or `langflower-launcher`. It is
+a portable app: no installation. The binary is unsigned, so Windows
+Defender and macOS Gatekeeper might warn. On macOS: right-click the
+file → **Open**. No Linux zip yet. Manual:
+[Desktop launcher](https://github.com/earthdmitriy/langflower/blob/master/docs/public/launcher.md).
 
-- **Chat sessions.** Node-internal state is the current architecture, so
-  serializable chat-session mechanics are hard. Maybe later.
-- **Image and video.** No asset management for multimodal models. Not yet.
-- **No built-in IDE or git UI.** We are not reinventing those wheels. Use
-  the editor and git tools you already have.
+Langflower does not host a model. Live agent runs need you to **bring
+your own key** (BYOK): add an OpenAI-compatible provider in Settings (gear icon)
+and paste the API key there. Pointing at an environment variable is
+optional. Simple nodes and the Fake LLM work without a key.
 
-## Quick start
-
-Requires **Node.js ≥ 22**.
+From a terminal:
 
 One-shot OS installers (Node LTS if needed + global `langflower`):
 [install/](install/) (`windows.ps1`, `linux.sh`, `macos.sh`).
@@ -140,12 +98,43 @@ npm run install-local
 npx langflower
 ```
 
-Langflower opens a local UI at `http://127.0.0.1:4010` (or `--port` / the port
-in `.langflower/config.json`) for the selected folder. Use `-p` to run several
-instances from different folders at once.
+The CLI opens a local UI at `http://127.0.0.1:4010` (or `--port` / the
+port in `.langflower/config.json`) for the selected folder. Use `-p` to
+run several instances from different folders at once.
 
 Full walkthrough: [Getting started](https://github.com/earthdmitriy/langflower/blob/master/docs/public/getting-started.md).
 
+## How it works
+
+1. Start Langflower with a project folder.
+2. Open a workflow on the canvas, or create one for the task.
+3. Run it and watch agents, tools, checks, and file changes move through
+   visible stages.
+4. Approve, reject, or add feedback when the workflow asks for a human
+   decision.
+5. Find the resulting files and data in the same workspace.
+
+## What it lacks
+
+- **Chat sessions.** You cannot save a chat and reopen it tomorrow.
+  Agent state lives inside the node for now. Maybe later.
+- **Image and video.** No asset management for multimodal models. Not yet.
+- **No built-in IDE or git UI.** We are not reinventing those wheels. Use
+  the editor and git tools you already have.
+
+## Under the hood
+
+The core is a reactive runtime. The **node SDK** is the public contract:
+any node that follows it can run on that runtime. **Common nodes** is the
+built-in catalog. It uses the same SDK as custom node packs.
+
+The **server** compiles user-defined nodes and owns the live run. The
+**UI** is a thin browser client over WebSocket; it does not own the
+workflow.
+
+For a short builder-oriented picture, see
+[How it works](https://github.com/earthdmitriy/langflower/blob/master/docs/public/how-it-works.md).
+
 Maintainers (monorepo only): [docs/RELEASE.md](https://github.com/earthdmitriy/langflower/blob/master/docs/RELEASE.md),
 [packages/cli/README.md](https://github.com/earthdmitriy/langflower/blob/master/packages/cli/README.md).
 
@@ -155,6 +144,7 @@ Shipped with the npm package under [`docs/public/`](https://github.com/earthdmit
 
 | Want to…                         | Start here                                                                                                 |
 | -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Start without a terminal         | [Desktop launcher](https://github.com/earthdmitriy/langflower/blob/master/docs/public/launcher.md)         |
 | Install and first run            | [Getting started](https://github.com/earthdmitriy/langflower/blob/master/docs/public/getting-started.md)   |
 | Understand the product           | [Product overview](https://github.com/earthdmitriy/langflower/blob/master/docs/public/product.md)          |
 | Use the canvas and runs          | [Using the editor](https://github.com/earthdmitriy/langflower/blob/master/docs/public/using-the-editor.md) |

package/dist/{chunk-526FJL62.js → chunk-AO33IM2J.js}

@@ -3,7 +3,7 @@ const require = __lfCreateRequire(import.meta.url);
 
 import {
   createProjectHarness
-} from "./chunk-WQZHA5FM.js";
+} from "./chunk-NIRPHJLO.js";
 import "./chunk-EAZMCX37.js";
 
 // packages/cli/dist/eval-command.js

package/dist/{chunk-WQZHA5FM.js → chunk-NIRPHJLO.js}

@@ -2,6 +2,75 @@ import { createRequire as __lfCreateRequire } from 'node:module';
 const require = __lfCreateRequire(import.meta.url);
 
 
+// packages/tools/dist/builtins/args.js
+var asString = (args, key) => {
+  const value = args[key];
+  return typeof value === "string" ? value : void 0;
+};
+var asNumber = (args, key) => {
+  const value = args[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+};
+var asBoolean = (args, key, defaultValue) => {
+  const value = args[key];
+  return typeof value === "boolean" ? value : defaultValue;
+};
+
+// packages/tools/dist/builtins/ask_user/tool.js
+var ASK_USER_ABORTED = "ask_user aborted.";
+var invokeWithAbort = (work, signal) => {
+  if (signal === void 0) {
+    return work;
+  }
+  if (signal.aborted) {
+    return Promise.reject(new Error(ASK_USER_ABORTED));
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      signal.removeEventListener("abort", onAbort);
+      reject(new Error(ASK_USER_ABORTED));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    void work.then((text) => {
+      signal.removeEventListener("abort", onAbort);
+      resolve(text);
+    }, (error) => {
+      signal.removeEventListener("abort", onAbort);
+      reject(error instanceof Error ? error : new Error(String(error)));
+    });
+  });
+};
+var invoke = async (ctx, args) => {
+  const question = asString(args, "question");
+  if (question === void 0 || question.trim().length === 0) {
+    throw new Error("ask_user requires string argument \xABquestion\xBB.");
+  }
+  if (ctx.askUser === void 0) {
+    throw new Error("ask_user requires a live HITL host. No askUser hook is bound on this harness.");
+  }
+  return invokeWithAbort(ctx.askUser({ question: question.trim() }), ctx.signal);
+};
+var askUserTool = {
+  id: "ask_user",
+  registration: {
+    toolId: "ask_user",
+    name: "ask_user",
+    description: "Do not guess. If you are not sure, ask the user. Pauses the run so the operator can provide additional information.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        question: {
+          type: "string",
+          description: "The question to show the operator. Be specific about what you need."
+        }
+      },
+      required: ["question"],
+      additionalProperties: false
+    }
+  },
+  invoke
+};
+
 // packages/tools/dist/builtins/bash/tool.js
 import { spawn } from "node:child_process";
 
@@ -80,20 +149,6 @@ var formatNotFound = async (absolutePath, userPath) => {
   return `File not found: \xAB${userPath}\xBB.${hint}`;
 };
 
-// packages/tools/dist/builtins/args.js
-var asString = (args, key) => {
-  const value = args[key];
-  return typeof value === "string" ? value : void 0;
-};
-var asNumber = (args, key) => {
-  const value = args[key];
-  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
-};
-var asBoolean = (args, key, defaultValue) => {
-  const value = args[key];
-  return typeof value === "boolean" ? value : defaultValue;
-};
-
 // packages/tools/dist/builtins/fence.js
 var fenceOptions = (ctx) => ({
   denyPaths: ctx.denyPaths,
@@ -103,7 +158,7 @@ var displayPath = (ctx, absolute) => toHarnessDisplayPath(ctx.projectRoot, absol
 
 // packages/tools/dist/builtins/bash/tool.js
 var MAX_BASH_OUTPUT = 1e5;
-var invoke = async (ctx, args) => {
+var invoke2 = async (ctx, args) => {
   if (!ctx.bashEnabled) {
     throw new Error("bash is disabled (default-deny). Enable bash on the project harness to run shell commands.");
   }
@@ -170,13 +225,13 @@ var bashTool = {
       additionalProperties: false
     }
   },
-  invoke
+  invoke: invoke2
 };
 
 // packages/tools/dist/builtins/create/tool.js
 import fs2 from "node:fs/promises";
 import path2 from "node:path";
-var invoke2 = async (ctx, args) => {
+var invoke3 = async (ctx, args) => {
   const userPath = asString(args, "path");
   const content = asString(args, "content");
   if (userPath === void 0 || content === void 0) {
@@ -221,12 +276,12 @@ var createTool = {
       additionalProperties: false
     }
   },
-  invoke: invoke2
+  invoke: invoke3
 };
 
 // packages/tools/dist/builtins/delete/tool.js
 import fs3 from "node:fs/promises";
-var invoke3 = async (ctx, args) => {
+var invoke4 = async (ctx, args) => {
   const userPath = asString(args, "path");
   if (userPath === void 0) {
     throw new Error("delete requires string argument \xABpath\xBB.");
@@ -261,12 +316,12 @@ var deleteTool = {
       additionalProperties: false
     }
   },
-  invoke: invoke3
+  invoke: invoke4
 };
 
 // packages/tools/dist/builtins/edit/tool.js
 import fs4 from "node:fs/promises";
-var invoke4 = async (ctx, args) => {
+var invoke5 = async (ctx, args) => {
   const userPath = asString(args, "path");
   const oldString = asString(args, "oldString");
   const newString = asString(args, "newString");
@@ -323,7 +378,7 @@ var editTool = {
       additionalProperties: false
     }
   },
-  invoke: invoke4
+  invoke: invoke5
 };
 
 // packages/tools/dist/builtins/glob/tool.js
@@ -546,7 +601,7 @@ var walkFiles = async (root, dir, options = true) => {
 
 // packages/tools/dist/builtins/glob/tool.js
 var MAX_GLOB_MATCHES = 200;
-var invoke5 = async (ctx, args) => {
+var invoke6 = async (ctx, args) => {
   const pattern = asString(args, "pattern");
   if (pattern === void 0) {
     throw new Error("glob requires string argument \xABpattern\xBB.");
@@ -599,7 +654,7 @@ var globTool = {
       additionalProperties: false
     }
   },
-  invoke: invoke5
+  invoke: invoke6
 };
 
 // packages/tools/dist/builtins/grep/tool.js
@@ -958,7 +1013,7 @@ var runGrepCascade = async (input, deps = {}) => {
 };
 
 // packages/tools/dist/builtins/grep/tool.js
-var invoke6 = async (ctx, args) => {
+var invoke7 = async (ctx, args) => {
   const pattern = asString(args, "pattern");
   if (pattern === void 0) {
     throw new Error("grep requires string argument \xABpattern\xBB.");
@@ -1014,7 +1069,7 @@ var grepTool = {
       additionalProperties: false
     }
   },
-  invoke: invoke6
+  invoke: invoke7
 };
 
 // packages/tools/dist/builtins/read/tool.js
@@ -1048,7 +1103,7 @@ var sliceLines = (content, args) => {
   }
   return truncated;
 };
-var invoke7 = async (ctx, args) => {
+var invoke8 = async (ctx, args) => {
   const userPath = asString(args, "path");
   if (userPath === void 0) {
     throw new Error("read requires string argument \xABpath\xBB.");
@@ -1104,13 +1159,13 @@ var readTool = {
       additionalProperties: false
     }
   },
-  invoke: invoke7
+  invoke: invoke8
 };
 
 // packages/tools/dist/builtins/write/tool.js
 import fs10 from "node:fs/promises";
 import path8 from "node:path";
-var invoke8 = async (ctx, args) => {
+var invoke9 = async (ctx, args) => {
   const userPath = asString(args, "path");
   const content = asString(args, "content");
   if (userPath === void 0 || content === void 0) {
@@ -1143,7 +1198,7 @@ var writeTool = {
       additionalProperties: false
     }
   },
-  invoke: invoke8
+  invoke: invoke9
 };
 
 // packages/tools/dist/builtins/catalog.js
@@ -1155,7 +1210,8 @@ var BUILTIN_TOOLS = [
   writeTool,
   createTool,
   deleteTool,
-  bashTool
+  bashTool,
+  askUserTool
 ];
 var BUILTIN_TOOL_IDS = BUILTIN_TOOLS.map((tool) => tool.id);
 var BUILTIN_REGISTRATIONS = BUILTIN_TOOLS.map((tool) => tool.registration);
@@ -1172,7 +1228,8 @@ var DEFAULT_PERMISSION_CONFIG = {
   write: { "*": "allow" },
   create: { "*": "allow" },
   delete: { "*": "allow" },
-  bash: { "*": "allow" }
+  bash: { "*": "allow" },
+  ask_user: { "*": "allow" }
 };
 var DECISION_RANK = {
   deny: 3,
@@ -1261,6 +1318,9 @@ var permissionDetailForCall = (toolId, args) => {
   if (toolId === "bash") {
     return typeof args.command === "string" ? args.command : "";
   }
+  if (toolId === "ask_user") {
+    return typeof args.question === "string" ? args.question : "";
+  }
   if (typeof args.path === "string" && args.path.length > 0) {
     return args.path.replace(/\\/g, "/");
   }
@@ -1385,7 +1445,8 @@ var createProjectHarness = (options) => {
     projectRoot: options.projectRoot,
     denyPaths: options.denyPaths ?? [],
     allowedRoots: options.allowedRoots ?? [],
-    bashEnabled: options.bashEnabled === true
+    bashEnabled: options.bashEnabled === true,
+    ...options.askUser !== void 0 ? { askUser: options.askUser } : {}
   };
   const permission = {
     ...DEFAULT_PERMISSION_CONFIG,