langflower 0.0.9 → 0.1.0

package/README.md

@@ -3,38 +3,63 @@
 > **Disclaimer:** Langflower is currently in internal testing. Anyone can
 > download and try it, but some functions may not be stable.
 
-**Turn a local folder into a repeatable AI workflow.**
+## Key concept: everything is a node
 
-Point Langflower at a workspace, choose or create a visual workflow, and let
-it read, create, review, and update files there. You see every stage on the
-canvas and decide what must happen before the next stage begins.
+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.
 
-The workflow decides the process — not a model deciding it is “done.”
+That is enough for complex processing chains — including loops and
+conditions.
 
-![Langflower starter workflow](https://raw.githubusercontent.com/earthdmitriy/langflower/master/docs/img/starter.png)
+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
 
-## What can you use it for?
+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.
 
-### Ship a code change
+**Not another chat harness. A local node graph.**
 
-Turn a task into a visible pipeline: clarify the request, implement the
-change, review it, run QA, and accept the result. You can stop or redirect
-the work at the stages that matter.
+### Keep everything local
 
-### Write and refine files
+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.
 
-Create an article or prompt in your workspace, review its tone and facts, then
-revise it in place. The useful output is a file you own, not only a chat
-transcript.
+### Scoped to a folder
 
-### Build a knowledge base
+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.
 
-Ingest project documentation, resolve duplicates or contradictions, review the
-proposed changes, and maintain a project wiki or Obsidian vault.
+### Extensible even now
 
-Langflower also supports research fan-out and synthesis, reusable skills,
-prompt refinement, regression gates, and multi-agent review. Browse the
-[workflow ideas](https://github.com/earthdmitriy/langflower/blob/master/docs/public/workflows.md).
+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.
+
+![Langflower starter workflow](https://raw.githubusercontent.com/earthdmitriy/langflower/master/docs/img/starter.png)
 
 ## How it works
 
@@ -46,55 +71,61 @@ prompt refinement, regression gates, and multi-agent review. Browse the
    decision.
 5. Find the resulting files and data in the same workspace.
 
-The graph is a **hard harness**: it defines the order of work. If review, QA,
-or approval is part of the workflow, an agent cannot silently skip it because
-it is confident in its own answer. Bring your own review gate — Langflower
-enforces it, so LLMs cannot skip or bypass that step.
+## Under the hood
 
-## Why Langflower
+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.
 
-- **Your folder stays the centre of work.** Read and write files locally,
-  rather than leaving the result in a provider-hosted chat history.
-- **You stay in control.** Workflows can request approval before sensitive
-  file edits or shell commands run.
-- **Human review is built in.** Ask for a plan review, fact check, rewrite, or
-  approval exactly where it makes sense in the process.
-- **Long tasks do not own your browser tab.** Close the tab and return later;
-  the session continues and the UI catches up when you reconnect.
-- **Reuse a process, not just a prompt.** Build a workflow once, then apply it
-  to similar folders and tasks.
-- **Extend it when the defaults are not enough.** Add markdown skills under
-  `.langflower/skills/` or custom nodes under `.langflower/nodes/`.
-
-## Why it stays reliable while you work
-
-Langflower's runtime treats every workflow step as a live exchange of data.
-That means a step can naturally wait for your input and continue when you
-reply — human review is part of the workflow, not a special interruption
-mode.
-
-The server owns the active session, while the browser is a view of it. Closing
-or reopening a tab does not create a competing workflow state or cancel a
-long-running job; the UI reconnects to the current progress.
+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).
 
+## 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.
+
 ## How it compares
 
-Langflower gives you graph-based chaining like mature orchestration tools —
-stages, branches, and review gates — but it is aimed at **local daily use**,
-not at shipping a backend service or wiring a cloud automation platform.
+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.
 
-Build a reusable workflow once for coding, documentation, article writing, or
-any similar desk work, then run it against the folders and tasks you already
-touch every day. The canvas keeps the process visible and repeatable; the
-project folder stays where the work happens.
+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.
+
+## What it lacks
+
+- **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.
 
 ## Quick start
 
 Requires **Node.js ≥ 22**.
 
+One-shot OS installers (Node LTS if needed + global `langflower`):
+[install/](install/) (`windows.ps1`, `linux.sh`, `macos.sh`).
+
 ```bash
 npm install -g langflower
 langflower
@@ -122,17 +153,12 @@ Maintainers (monorepo only): [docs/RELEASE.md](https://github.com/earthdmitriy/l
 
 Shipped with the npm package under [`docs/public/`](https://github.com/earthdmitriy/langflower/tree/master/docs/public):
 
-| Want to…                     | Start here                                                                                                 |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| 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) |
-| Browse workflow ideas        | [Workflow ideas](https://github.com/earthdmitriy/langflower/blob/master/docs/public/workflows.md)          |
-| Configure providers and keys | [Configuration](https://github.com/earthdmitriy/langflower/blob/master/docs/public/configuration.md)       |
-| Add skills or custom nodes   | [Extending](https://github.com/earthdmitriy/langflower/blob/master/docs/public/extending.md)               |
-| Builder runtime picture      | [How it works](https://github.com/earthdmitriy/langflower/blob/master/docs/public/how-it-works.md)         |
-
-## What Langflower is not
-
-Langflower is local and project-scoped. It is not a hosted multi-tenant cloud
-product or a generic cloud ETL clone.
+| Want to…                         | Start here                                                                                                 |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| 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) |
+| Browse workflow ideas            | [Workflow ideas](https://github.com/earthdmitriy/langflower/blob/master/docs/public/workflows.md)          |
+| Configure providers and keys     | [Configuration](https://github.com/earthdmitriy/langflower/blob/master/docs/public/configuration.md)       |
+| Add MCP, skills, or custom nodes | [Extending](https://github.com/earthdmitriy/langflower/blob/master/docs/public/extending.md)               |
+| Builder runtime picture          | [How it works](https://github.com/earthdmitriy/langflower/blob/master/docs/public/how-it-works.md)         |

package/docs/public/README.md

@@ -7,9 +7,9 @@ package).
 | Manual                                     | Topic                                     |
 | ------------------------------------------ | ----------------------------------------- |
 | [Getting started](getting-started.md)      | Install, first run, ports                 |
-| [Product overview](product.md)             | What Langflower is (and is not)           |
+| [Product overview](product.md)             | Local node graph: pitch, compare, lacks   |
 | [Using the editor](using-the-editor.md)    | Canvas, runs, human review, reconnect     |
 | [Workflow ideas](workflows.md)             | Common scenarios you can build            |
 | [Configuration](configuration.md)          | Providers, models, keys, project settings |
-| [Extending Langflower](extending.md)       | Skills and custom nodes                   |
+| [Extending Langflower](extending.md)       | MCP, skills, custom nodes (ToolHandle)    |
 | [How it works (builders)](how-it-works.md) | Short runtime picture for extenders       |

package/docs/public/configuration.md

@@ -44,8 +44,12 @@ the workflow.
 
 ## Custom nodes and skills
 
+MCP and skills are the common agent primitives. Custom nodes add graph
+processing or custom tools via **ToolHandle**.
+
 - Skills: markdown under `.langflower/skills/<name>/`
 - Custom nodes: packs under `.langflower/nodes/<pack>/`
+- MCP: palette nodes plus optional project `mcp` in `langflower.jsonc`
 
 See [Extending Langflower](extending.md).
 

package/docs/public/extending.md

@@ -1,5 +1,18 @@
 # Extending Langflower
 
+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.
+
+## MCP and skills
+
+Optional `mcp` entries in `.langflower/langflower.jsonc` declare stdio/http
+servers; palette MCP nodes emit **ToolHandle**s. Agents do not spawn MCP
+themselves. Permission floors for harness tools live in project config.
+Skills are markdown playbooks under `.langflower/skills/` (next section).
+
+See [Configuration](configuration.md).
+
 ## Skills
 
 Skills are markdown playbooks the agent can load. Add a folder:
@@ -15,8 +28,11 @@ do in your project.
 
 ## Custom nodes
 
-Built-in catalog nodes and your packs share the same authoring SDK. Default
-path for a simple node:
+Custom nodes share the same authoring SDK as the built-in catalog. Use them
+for graph processing, or to expose custom tools to agents as **ToolHandle**s
+on `tools` ports.
+
+Default path for a simple node:
 
 ```ts
 import { defineNode } from '@langflower/node-sdk';

package/docs/public/getting-started.md

@@ -6,6 +6,13 @@
 - A project folder on your machine (code, docs, or any workspace you want
   Langflower to work in)
 
+To install Node (latest LTS when missing or too old) and the global CLI in
+one step, download a single script from
+[install/](../../install/):
+[windows.ps1](../../install/windows.ps1),
+[linux.sh](../../install/linux.sh), or
+[macos.sh](../../install/macos.sh).
+
 ## Install and run
 
 ```bash

package/docs/public/how-it-works.md

@@ -5,11 +5,17 @@ architecture spec.
 
 ## Pieces you interact with
 
-1. **CLI** — starts a local server for one project folder and opens the UI.
-2. **Server** — owns the session, workflows on disk, and the live run.
-3. **Runtime** — executes the graph: nodes exchange data on typed ports.
-4. **UI** — canvas + feed are views of server-owned state over a WebSocket
-   contract. Reconnecting the browser does not invent a second run.
+1. **CLI** — starts a local server for one project folder and opens the UI
+   in your existing browser (not a bundled Electron shell).
+2. **Runtime** — wires **reactive nodes**. Ports are independent: a node can
+   receive on one input and emit on one output at any time.
+3. **Node SDK** — public contract (`@langflower/node-sdk`). Built-in
+   **common nodes** and custom packs use the same SDK.
+4. **Server** — composes those pieces, compiles user-defined node packs, and
+   owns the live run.
+5. **UI** — thin browser client. Canvas + feed listen to WebSocket events
+   from the server. Closing the tab does not stop the run; reopen and the
+   server catches the UI up.
 
 ## Why review “just works”
 
@@ -24,12 +30,13 @@ model cannot skip it by claiming it is finished.
 
 ## Extensibility surface
 
-| You add…     | Where                          |
-| ------------ | ------------------------------ |
-| Skills       | `.langflower/skills/`          |
-| Custom nodes | `.langflower/nodes/<pack>/`    |
-| Workflows    | `.langflower/workflows/`       |
-| Providers    | `.langflower/langflower.jsonc` |
+| You add…     | Where                                                        |
+| ------------ | ------------------------------------------------------------ |
+| MCP          | Palette MCP nodes + optional `mcp` in JSONC                  |
+| Skills       | `.langflower/skills/`                                        |
+| Custom nodes | `.langflower/nodes/<pack>/` — processing or ToolHandle tools |
+| Workflows    | `.langflower/workflows/`                                     |
+| Providers    | `.langflower/langflower.jsonc`                               |
 
 See [Extending](extending.md) and [Configuration](configuration.md).
 

package/docs/public/product.md

@@ -1,40 +1,50 @@
 # Product overview
 
-Langflower turns a **local folder** into a **repeatable AI workflow**.
+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.
 
-You point it at a workspace, open or create a visual workflow on a canvas, and
-let agents read, create, review, and update files there. You see every stage
-and decide what must happen before the next stage begins.
+Because ports fire on their own, an LLM agent is just another node: prompt
+and tools in; response out; streaming tool log, reasoning, and draft as
+extra outputs. LLM-specific logic stays inside that node. It does not leak
+through the rest of the app.
 
-**The workflow decides the process — not a model deciding it is “done.”**
+**Not another chat harness. A local node graph.**
 
-## Who it is for
+Langflower runs on your machine, scoped to a folder you open. Data, custom
+nodes, and workflows live there. You can reproduce what mature cloud tools
+offer at home, or on a closed network with internal LLM providers.
+
+The sequence is the workflow topology (a **hard harness**). QA, review, and
+code checks sit on the graph, so agents cannot skip them. Coding, chat,
+agent-to-agent dialogue, and custom gates are the same idea: wire nodes.
 
-- **Near term:** developers running Langflower against an existing code repo
-- **Also useful for:** writing and refining files, research-style fan-out, and
-  maintaining project documentation in the same folder
+## Who it is for
 
-## What makes it different
+Anyone with a local folder and a process they want on a graph. Coding in a
+repo is one scenario among others — writing, research fan-out, knowledge
+bases, and custom pipelines. Browse [workflow ideas](workflows.md).
 
-| Chat-style agent harnesses                           | Cloud / ETL graph tools                              |
-| ---------------------------------------------------- | ---------------------------------------------------- |
-| Pipeline order is fixed on the canvas (hard harness) | Aimed at **local daily work**, not hosting a service |
-| Review and QA stages cannot be skipped by the model  | Bootstrap into a real project folder quickly         |
-| You stay on your files, not only in chat history     | Same idea: reusable process, local folder centre     |
+## How it compares
 
-### Hard harness
+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.
 
-1. The **graph** is the law — stages and edges are authored, not chosen by the
-   model at runtime.
-2. Logic nodes (gates, asserts, branches) can fail closed between agents when
-   you need a check.
+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.
 
-## What Langflower is not
+## What it lacks
 
-- Not a hosted multi-tenant cloud product
-- Not a generic cloud ETL clone
-- Not a replacement for your editor — it works **with** the files in your
-  project folder
+- **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.
 
 ## Learn more
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "langflower",
-	"version": "0.0.9",
+	"version": "0.1.0",
 	"description": "Visual LLM-chain builder",
 	"type": "module",
 	"bin": {
@@ -27,7 +27,7 @@
 		"@langflower/websocket-bridge": "file:./vendor/websocket-bridge",
 		"@langflower/shared": "file:./vendor/shared",
 		"@langflower/server": "file:./vendor/server",
-		"@rx-evo/stateful-observable": "^0.5.2",
+		"@rx-evo/stateful-observable": "^0.6.0",
 		"rxjs": "^7.8.1",
 		"undici": "^7.28.0",
 		"@types/node": "^22.10.0",