Description
n8n-nodes-loomcycle
Community n8n nodes for the loomcycle agentic runtime — design and operate loomcycle agents directly from n8n’s visual builder.
This package realises Phase 2 / Vector 3 of the loomcycle ↔ n8n integration RFC: custom n8n nodes that let operators drive loomcycle from the n8n canvas, while loomcycle stays the agentic runtime substrate.
📦 Two editions — which one do I want?
This repo ships two parallel packages from two branches. Pick by where your n8n runs:
| | Slim (this package) | Full |
|—|—|—|
| npm | @loomcycle/n8n-nodes-loomcycle | @loomcycle/n8n-nodes-loomcycle-full |
| branch | main | full-edition |
| nodes | 22 | 26 |
| n8n Cloud verified | ✅ yes — passes n8n’s community-node scanner (zero deps, no langchain, no timers) | ❌ no — self-hosted only, install manually |
| AI-Agent Tool sub-nodes (Memory / Channel / Sub-Agent / MCP Server Tool) | — (wire the action nodes as Agent tools, or use the Chat Model) | ✅ included (langchain-based) |
| Triggers | poll-based (n8n schedules) | SSE-push + poll fallback (lower latency) |
| Run Wait for Completion op | — (use the Run Completed trigger / n8n Wait node) | ✅ included |
| Chat Model | @n8n/ai-node-sdk (langchain-free) | langchain BaseChatModel |
Use the Slim package (this one) if you’re on n8n Cloud, want the verified node, or don’t need the langchain Tool sub-nodes.
Switch to the Full edition if you’re self-hosted and want the extra nodes / SSE triggers / Wait op:
Self-hosted n8n → Settings → Community Nodes → Install:
@loomcycle/n8n-nodes-loomcycle-full
Both track the same loomcycle wire API and credential; they differ only in node surface + Cloud-eligibility. The rest of this README documents the slim package.
Requirements
These nodes are a thin n8n-shaped wrapper over loomcycle’s wire API — they call your loomcycle deployment, they don’t run an agent runtime inside n8n. So you need:
- A reachable loomcycle deployment + a bearer token (loomcycle’s
LOOMCYCLEAUTHTOKEN). Every node call goes out to the Base URL on the LoomCycle API credential. - loomcycle ≥ v0.9.2 for the substrate-admin ops (AgentDef / SkillDef / MCP Server); ≥ v0.12.x for the Schedule node and per-tool credentials. Basic Run / Memory / Channel ops work on older builds.
- n8n ≥ 1.82 (the package targets
n8n-workflow≥ 1.82).
– Self-hosted n8n: loomcycle can sit on localhost / your LAN (e.g. http://127.0.0.1:8787).
– n8n Cloud: loomcycle must be reachable from the public internet — a public HTTPS URL or a tunnel (Cloudflare Tunnel, ngrok, …) — because n8n Cloud makes the outbound call from its own network, not yours.
Quick install
In your n8n Settings → Community Nodes → Install:
@loomcycle/n8n-nodes-loomcycle
Once installed, configure the LoomCycle API credential with your loomcycle deployment’s bearer token + base URL.
The package lives under the @loomcycle npm org alongside @loomcycle/client — same trust boundary, same maintainer.
What’s in the box
Thirty-two nodes (27 action + 4 trigger + 1 AI-Agent cluster sub-node) plus one credential type. Zero runtime dependencies — n8n-Cloud-verification-ready.
Credential
GET /v1/_me (whoami) to validate the bearer resolves to a principal (tenant + scopes) — requires loomcycle ≥ v0.17. Under v0.17’s multi-tenant authorization (RFC L), the bearer is a tenant-scoped OperatorTokenDef token; provision it with the scopes your workflow’s operations need.Action nodes
As of 2.0.0 the former single multi-resource umbrella node is split into dedicated action nodes, each with its own canvas icon (n8n renders one icon per node type — separate nodes are the only way to give each entity a distinct glyph). They all share one credential and one wire client; they are drag-and-drop separate in the node picker.
Spawn / Spawn Batch / Send Input / Get Status / Get Transcript / Compact / Cancel / Cancel Turn / Replay Session / List Agents / List Runnable Agents. Spawn-time Sampling / Compaction / Run Timeout overrides live under Additional Fields. Spawn Batch fans out up to 32 runs (loomcycle ≥ v0.33); Compact summarises a parked run’s context (≥ v0.33). For interactive runs (loomcycle ≥ v1.1.1), enable Additional Fields → Interactive Session on Spawn — the node returns the runid once the run parks at endturn; steer it with Send Input and read final output via the Run Completed trigger. Cancel Turn stops the in-flight turn and parks the run without terminating it (RFC BH, ≥ v1.22); Replay Session replays a transcript into a new session on another agent (RFC BJ, ≥ v1.25); List Runnable Agents is the member-token-safe agent listing (RFC BY, ≥ v1.51). Spawn also accepts image input via Additional Fields → Image Binary Properties (RFC AT, ≥ v1.7) and reports token-budget crossings as a limits[] array (RFC AW, ≥ v1.11). (To wait for non-interactive completion, use the Run Completed trigger or n8n’s own Wait node.)Get Entry / List Entries / List Scope IDs / List Scopes / Set Entry / Delete Entry / Search / Embed Stats / Reembed / Backfill Embeddings / Purge Stale Embeddings. Search (RFC BV/BW, ≥ v1.47) returns one ranked list spanning k/v entries and document-chunk bodies, each hit tagged fact / note / document. The three embedding-maintenance ops are dry-run by default behind an explicit Commit toggle — Purge Stale Embeddings deletes. (Per-tool credentials userCredentials map on Spawn require loomcycle ≥ v0.12.x.)Publish / Subscribe / Peek / Ack / Await / Broadcast / List Channels / Create Channel / Update Channel / Delete Channel / Purge Channel. Await (fan-in) waits on a predicate across channels and Broadcast (fan-out) publishes to many atomically (loomcycle ≥ v0.25); yaml-declared channels remain immutable (but Purge is allowed on them).Create / Fork / Get / List Versions / Promote / Retire / Verify (content_sha256 round-trip). Create/Fork expose a Provider dropdown read live from GET /v1/config (≥ v1.38) and folded into the overlay; it always offers the unset default plus the synthetic Code-JS provider, which authors a deterministic JavaScript agent (RFC J).Register / Fork / Promote / Retire / Get / List Versions / Rediscover / Verify — dynamic MCP server registration (requires loomcycle ≥ v0.9.2)Create / Fork / Get / List Versions / Retire — substrate-native scheduled runs (RFC E; requires loomcycle ≥ v0.12.x). Fired runs land on the Run Completed trigger.Register / List / Delete — outbound pre/post-tool webhook callbacks; point the callback URL at an n8n Webhook trigger to call back into a workflow on matched tool calls.Create / Fork / Get / List Versions / Retire — inbound webhook endpoints (RFC H; requires loomcycle ≥ v0.14.x): an external POST to a loomcycle-hosted endpoint spawns an agent run / publishes to a channel. (Distinct from Hook above, which is outbound.)Create / Fork / Get / List Versions / Retire — register external A2A (Agent2Agent) agents loomcycle can call as tools (RFC G; requires loomcycle ≥ v0.14.x).Create / Fork / Get / List Versions / Retire — manage the agent card loomcycle publishes to expose its own agents to external A2A clients (RFC G; requires loomcycle ≥ v0.14.x).List for User / List for Run / Resolve / Decline — human-in-the-loop over Interruption.ask: list pending agent questions and post a human’s answer back to unblock the parked run. Decline (RFC BH P2, ≥ v1.22) refuses to answer without killing the run — the agent’s Question tool returns a non-error “declined” and it continues. (Requires loomcycle’s consumer-MCP interruption backend.)Chat / Embeddings — direct calls to loomcycle’s LLM gateway (POST /v1/_llm/*) as a workflow step: provider routing + auth + retry handled substrate-side, no agent loop. For RAG / embedding pipelines. (Distinct from the Chat Model sub-node, which feeds an AI Agent.)Create / Fork / Get / List Versions / Retire — versioned memory-backend definitions (in-process or external REST store + ranker) that agents’ Memory tool dispatches to (RFC I; requires loomcycle ≥ v0.15).Get / List / Retire — operator-token lifecycle (RFC L; requires loomcycle ≥ v0.17). Mint + rotate are intentionally NOT here — those return the token secret, which must not enter n8n execution data; do them via the loomcycle Web UI / CLI.Create / List / Get / Restore / Delete / Export URL / Pause Runtime / Resume Runtime / Get Runtime State / Resolve Probe — runtime snapshot backup + restore (loomcycle ≥ v0.8.17): snapshot before a deploy, restore on rollback. Restore accepts a stored snapshot ID or an inline envelope; Export URL returns a bearer-authed download link. The four runtime-maintenance ops are grouped here because they are what you reach for around a snapshot: pause so nothing is admitted mid-capture, capture, deploy or restore, resume. Note pausing does not stop runs already in flight — Get Runtime State reports what still is.Create / Get / List / List Ephemeral / Delete / Purge — filesystem Volumes (RFC AH; requires loomcycle ≥ v1.1). Provision named ro/rw filesystem roots for agents (the runtime derives the on-disk path); since v1.1 a Volume is the only way an agent gets filesystem access. Delete unmaps but keeps the files; Purge removes the tree.Resolve / List / Stat / Make Directory / Move / Remove — the Path VFS (RFC AL; requires loomcycle ≥ v1.4): a Unix-like filesystem naming Memory entries / Volume mounts / Documents by human-readable path (e.g. /docs/launch). Scope (agent / user / tenant) resolves server-side from the bearer.Backlinks / Related / Unlinked Mentions), tags, types, Query Chunks (structured filters, Under Path, or a validator-gated read-only SQL escape hatch), per-chunk History / Get Version / Diff Revisions, Markdown and JSON Canvas import-export, image assets, and peer federation (Set Remote / Sync / Diff Remote). A chunk body is embedded on write, which is what makes Memory → Search find it.Remember / Upsert Fact / Supersede Fact / List Facts / Judge Fact / Verbatim Answer / Verification Stats / Graph Recall / Propose Entity / Search. A fact stores the exact source span it was drawn from and a write-time judge checks the claim against it; a fact that fails is withheld, not deleted (pass Include Refuted to audit it). judgedat / judgedby are server-stamped with no wire field, so a caller cannot record a machine verdict as an operator one. Corrections go through Supersede Fact — Remember is additive only, there is no forget.Create / Fork / Get / List Versions / Retire — register a peer loomcycle instance as a document source (RFC CE; requires loomcycle ≥ v1.54), which the Document node’s Set Remote / Sync ops consume. Operator-admin only; the overlay carries apikeyenv, the env-var name of the peer bearer, never a plaintext token.List / Get / Create / Fork / Delete / Run / Render Diagram — Agent Teams (RFC AP; requires loomcycle ≥ v1.17.1). A TeamDef is a versioned state-machine graph of agent roles: states carry a handler (agent / parallel / consolidator / terminal) and transitions are gated on each state’s outcome. Run walks the graph, spawning an agent per state until a terminal — and bound to a Document chunk task board it persists chunk.status per transition, so progress is durable and a later Run resumes rather than restarting. Render Diagram emits Mermaid stateDiagram-v2, optionally highlighting the state a walk has reached. This is the closest analogue loomcycle has to an n8n workflow: n8n designs and triggers it, the substrate runs it under its own admission control.List Users / Inspect Subject / List Tenants — read-only “who is in this deployment and what is held for them” (loomcycle ≥ v1.46). Inspect aggregates one subject’s activity, chats, memory, documents, budget and usage in a single call. There is no create or update: a user here is derived from run activity, not stored. List Tenants needs an operator-admin token and refuses a tenant-scoped one outright rather than filtering.Report / Execute — subject erasure (RFC BL P5; requires loomcycle ≥ v1.45, and the deployment must set LOOMCYCLEAUDITLOG_PATH from v1.55). The natural home for a GDPR data-subject-request workflow. Three tiers: deletable, subject-keyed-but-uncovered, and residue — facts about the subject in scopes they do not own. Execute is a dry run unless you commit, and committing additionally requires retyping the subject. Persist the Execute output: residue is traceable only through the subject’s chats, which Execute deletes, so a later report shows 0 while those facts remain — the response is the only durable record.List / List Tokens / Revoke Token — tenant-owned users and their delegated bearer tokens (RFC BX P2; requires ≥ v1.50). The tenant is always server-derived, so no operation takes one. Reads plus one revocation, by design. Identity CRUD is absent because provisioning and removing users is operator work for the loomcycle CLI / Web UI, not a workflow side effect; Revoke Token stays because cutting off a leaked credential is exactly what you want to automate on an alert. Minting is absent for a stronger reason — the substrate returns the bearer plaintext once, and it must not land in execution data.Usage Report / List Limits / Get Config — token + cost attribution (RFC AV; ≥ v1.10) and a read of the per-scope token budgets (RFC AW; ≥ v1.11). Group a report by source to see which key actually paid — operator vs tenant. Read-only by design: budget writes stay operator-only even for a tenant member, and setLimit is a full-row upsert whose omitted tier clears that ceiling — too easy to do damage with from a half-filled form. Set budgets via the CLI / Web UI.List / Get / Search / Related / Rename / Annotate / Pin / Archive / Recap / Resume — past chats as first-class objects (RFC BE; requires loomcycle ≥ v1.20). The owner is resolved server-side, so you pick a scope (self / user / tenant / global — the last admin-only) rather than naming one. Get renders a transcript as structured events, full Markdown, or Conversation (user and assistant turns only) — use the last when feeding a chat to a model, since it strips the tool traffic that is usually most of the tokens. ⚠️ Search matches the chat TITLE only, not content or summaries; Related is the semantic path and is what you want for “find the conversation about X”.> Migration from 1.x: the umbrella LoomCycle node (type loomCycle) was removed. Workflows built on 1.x must swap each LoomCycle node for the matching dedicated node (e.g. a LoomCycle node with Resource = Memory → LoomCycle Memory); operations and parameters are otherwise unchanged.
Trigger nodes
All three triggers use n8n’s polling framework (poll()), scheduled by n8n’s Poll Times — no in-node timers (n8n Cloud forbids timer primitives in community nodes). Detection latency is the poll interval.
LOOMCYCLEMEMORYCHANGESENABLED=1). loomcycle POSTs HMAC-signed batches to this node’s webhook URL on every memory / document write, so it needs no polling. Events are value-free — each carries the coordinate of what changed, never the value — so follow it with Memory → Get Entry or Document → Get Chunk to read the current state. Signature verification fails closed, and because delivery is at-least-once with a persisted cursor on the loomcycle side, the node dedupes on the monotonic seq. Subscriptions are operator-yaml only: add a changesubscriptions: entry pointing callback_url at the Production webhook URL.parentAgentId.auto-ack (at-most-once, subscribeChannel poll-once) or peek + explicit ack (at-least-once, cursor persisted in workflow static data).interrupt_id. Wire the output to a human channel (Slack / email / form) and feed the answer back via LoomCycle Interruption → Resolve.Cluster sub-node (plugs into n8n’s AI Agent)
POST /v1/_llm/chat) instead of a direct provider SDK. Single credential covers all providers; loomcycle’s resolver picks provider / model at request time; per-user quota tracking; single audit log. Supports tool calling. Built on @n8n/ai-node-sdk (BaseChatModel) — langchain-free, so the package stays Cloud-verifiable. No agent loop — this is the thin gateway shim, not the full runtime; use the LoomCycle Run action node for the full loop.> Removed in v3.0.0: the langchain-based Memory / Channel / Sub-Agent / MCP Server Tool sub-nodes. n8n Cloud bans community nodes that depend on @langchain/core, and @n8n/ai-node-sdk has no tool-supply API yet. To give an AI Agent loomcycle capabilities, wire the action nodes (Run / Memory / Channel) as the Agent’s tools, or call loomcycle via the Chat Model. The Tool sub-nodes will return if/when the SDK adds a tool path.
Configure the credential
In n8n, navigate to Settings → Credentials → New and pick LoomCycle API.
| Field | Required | Notes |
|—|—|—|
| Base URL | yes | e.g. http://127.0.0.1:8787 |
| Bearer Token | yes | Matches loomcycle’s LOOMCYCLEAUTHTOKEN env var |
| Default User ID | no | Falls through to any node where userId is left empty |
| Default User Tier | no | Same fall-through |
| MCP URL (optional) | no | Only needed if you reference loomcycle’s MCP server from n8n’s MCP Client Tool sub-node (Vector 1) |
Click Test → a green checkmark means the bearer authenticated. Behind the scenes: GET /v1/_me with Authorization: Bearer — this resolves the token’s principal (tenant + scopes), so an invalid / expired / wrong-tenant token fails the test here rather than at runtime. (Requires loomcycle ≥ v0.17; on older deployments, change is needed — see the editions/compat notes.)
Examples
Four importable workflow JSONs in examples/ cover the canonical patterns:
| # | File | Pattern |
|—|—|—|
| 01 | 01-multi-agent-research.json | Researcher → summariser → channel digest |
| 02 | 02-slack-loomcycle-slack.json | Slack trigger → loomcycle agent → Slack reply |
| 03 | 03-daily-activity-report.json | Cron → listAgents → JS aggregation → email |
| 04 | 04-n8n-as-loomcycle-tool.json | Vector 2 — n8n workflow as MCP server consumed by loomcycle |
(The AI-Agent + cluster-tool examples were removed in v3.0.0 alongside the langchain Tool sub-nodes.)
Import via Workflows → Import from File, then attach your LoomCycle API credential. See examples/README.md for per-example prerequisites + caveats.
Provisioning MCP servers dynamically
The LoomCycle MCP Server action node registers HTTP / Streamable-HTTP MCP servers in the substrate at workflow-design time (run it once, ahead of any Run nodes), so spawned agents can reference them as mcp:
1. Register: mcpServerDef({op: 'create', name, transport, url, headers, promote: true}). Re-registering identical content is a no-op (deduplicated: true) on loomcycle ≥ v0.20, so you can run Register unconditionally — no Get-first dance needed.
2. Manage: Fork / Promote / Retire / Rediscover / Verify the registration as versioned MCPServerDefs.
3. Spawn agents (via LoomCycle Run) with allowed_tools: ['mcp to give them the MCP server’s tool surface.
Tool auto-discovery (loomcycle ≥ v0.20). Register/Fork run the MCP tools/list handshake at registration and return a discovered count in the node output — you can see the tool surface immediately instead of waiting for first call. It’s best-effort: an unreachable peer still registers and self-heals lazily. Untick Discover Tools at Registration to register connection metadata only.
Two create-time checks to know about (v0.20): the URL host is validated against the allowlist at registration (a loopback / RFC1918 callback host must be in the private host allowlist, not just the general one), and inner ${LOOMCYCLE_*} header tokens are expanded at registration — so those env vars must exist on the deployment before you Register, or the discovery handshake authenticates with an unresolved token.
> (Through v2.x this was an auto-provisioning AI-Agent cluster tool. That tool was langchain-based and removed in v3.0.0; the same substrate capability is now driven explicitly via the MCP Server action node.)
The env-var mirror
The Headers field accepts template strings (not plaintext credentials):
Authorization: Bearer ${LOOMCYCLESLACKTOKEN}
At request time, loomcycle substitutes ${LOOMCYCLE} tokens from its own environment. The operator must mirror the credential: it lives in n8n (for n8n’s own use, if any) AND in loomcycle’s env (LOOMCYCLESLACKTOKEN=…). Plaintext credentials never traverse the n8n → loomcycle wire. The MCP Server node’s UI renders a “Required env vars on loomcycle” notice listing the ${LOOMCYCLE} tokens it detects in your headers.
Code-JS agents
code-js (RFC J) is a loomcycle synthetic provider: the agent runs deterministic JavaScript instead of an LLM — replayable, no model cost. A code-js agent is just an Agent Definition with provider: code-js (and no model), spawned through the normal LoomCycle Run → Run Completed lifecycle. No dedicated node is needed.
Author it inline from n8n (loomcycle ≥ v0.20): on LoomCycle Agent Definition → Create (or Fork), pick Code-JS in the Provider dropdown and write the source in the JavaScript Code editor that appears. The node folds it into the overlay as code_body; loomcycle compiles + content-hashes it at registration. No host filesystem access needed — the code travels the wire like any other definition field.
One host prerequisite: enable the provider with LOOMCYCLECODEAGENTSENABLED=1 (default off — operator-trust, same posture as the Bash tool; or registration is refused). Inline source is capped at ~256 KB. For reproducible runs, optionally LOOMCYCLECODEAGENTSDETERMINISTIC=1.
> Filesystem fallback (still supported): leave the JavaScript Code editor empty and loomcycle falls back to agentcode/ (under LOOMCYCLECODEAGENTSROOT) on the host, where code_body wins when both are present.
Passing metadata to agents
loomcycle ≥ v0.21 adds a non-secret metadata channel to the agent. A code-js agent reads it as input.metadata; an LLM agent receives it as a trusted prompt block. It’s for context, not secrets (metadata is safe to log) — keep tokens in the credentials fields. Three entry points, all surfaced as a Metadata (JSON) field:
Metadata (JSON) under Additional Fields. Per-call and trusted (first-party bearer); not inherited by a continuation.Metadata (JSON), delivered on every scheduled fire. Override it per fork for the canonical “one template, a different repo per tenant” pattern. – Static Metadata (JSON) — operator-authored, delivered trusted.
– Request-sourced — add payloadmapping entries with runmetadata. targets in the Advanced Overlay (e.g. {"runmetadata.repo": "$.repository.fullname"}). These are projected from the inbound POST body and delivered untrusted (fenced in a input.payloadmetadata for code-js).
The Webhook node also gains Per-Delivery Credentials (template strings → user_credentials), reaching parity with the Schedule node’s per-fire credentials.
Human-in-the-loop
A loomcycle agent can call Interruption.ask to pause and ask a human a question (optionally with a fixed set of options). n8n is the natural place to answer it — and the LoomCycle: Interrupt Pending trigger + LoomCycle Interruption node close the loop end-to-end:
1. Interrupt Pending trigger fires when a new pending ask appears for a user (listUserInterrupts, deduped by interruptid). Each item carries runid, interrupt_id, question, and any options.
2. Route it to a human — a Slack message, an email, an n8n Form, an approval step.
3. LoomCycle Interruption → Resolve posts the human’s answer back (resolveInterrupt(runid, interruptid)). The parked agent unblocks and continues. When the ask declared options, the answer must be one of them (validated server-side).
> Requires loomcycle’s consumer-MCP interruption backend so an external resolver is accepted (set in the deployment’s yaml). Without it, asks are answered through loomcycle’s own Web UI / CLI instead.
Local development install
Want to install from the local checkout for development?
In this package:
git clone https://github.com/denn-gubsky/n8n-nodes-loomcycle.git
cd n8n-nodes-loomcycle
npm install
npm run build
npm linkIn your n8n install (e.g. ~/.n8n/nodes):
cd ~/.n8n/nodes
npm link @loomcycle/n8n-nodes-loomcycleThen restart n8n. The 20 nodes appear under the "LoomCycle" prefix in
the node picker.
Compatibility
Loomcycle version compatibility
| Feature | Min loomcycle | Notes |
|—|—|—|
| Run / Memory (read) / basic Channel | v0.8.x | Substrate stability since v0.8.4 |
| Channel CRUD (publish / subscribe / peek / ack) | v0.9.2 | PR #180 on the substrate |
| AgentDef + SkillDef substrate-admin ops | v0.8.22 | PR #163 |
| content_sha256 Verify op | v0.9.x | PR #175 |
| MCPServerDef substrate (dynamic MCP) | v0.9.2 | PR #177; required by the MCP Server action node |
| parentAgentId filter | v0.9.2 | used by the Run Completed trigger |
| LLM Gateway (POST /v1/_llm/chat) powering LoomCycle Chat Model | v0.10.x | enables n8n AI Agent’s Chat Model slot to route through loomcycle |
| Per-tool credentials (RFC F) + Schedule (RFC E) | v0.12.x | Schedule action node |
| Inbound Webhooks (RFC H) + A2A (RFC G) | v0.14.x | Webhook + A2A Agent / A2A Server Card action nodes |
| Interactive run steering (RFC AI) — Run → Send Input + Spawn’s Interactive Session | v1.1.1 | push operator turns into a run parked at end_turn |
| Filesystem Volumes (RFC AH) — Volume node | v1.1 | named ro/rw filesystem roots; the only way an agent gets filesystem access since v1.1 |
| Path VFS (RFC AL) — Path node | v1.4 | name Memory / Volumes / Documents by human-readable path |
| Image / vision input (RFC AT) | v1.7 | Run → Spawn → Image Binary Properties; base64 only, no URL form |
| Per-scope token budgets (RFC AW) | v1.11 | limits[] on the Spawn result |
| Turn-scoped cancel + decline (RFC BH) | v1.22 | Run → Cancel Turn; Interruption → Decline |
| Session replay (RFC BJ P4) | v1.25 | Run → Replay Session |
| Live provider cascade (GET /v1/config) | v1.38 | Agent Definition Provider dropdown |
| Embedding maintenance | v1.46 | Memory → Backfill / Purge Stale Embeddings |
| Unified memory search (RFC BV/BW) | v1.47 | Memory → Search / Embed Stats / Reembed |
| Agent Teams (RFC AP) — Team node | v1.17.1 | state-machine graphs of agent roles; board-bound runs resume |
| Usage + cost attribution (RFC AV) | v1.10 | Usage → Usage Report |
| Per-scope token budgets (RFC AW) — read | v1.11 | Usage → List Limits; limits[] on a Run result |
| Subject erasure (RFC BL P5) — Erasure node | v1.45 | also needs LOOMCYCLEAUDITLOG_PATH from v1.55 |
| Directory (derived users / tenants) | v1.46 | Directory node; List Tenants is admin-only |
| Delegated users + tokens (RFC BX) — User node | v1.50 | needs a persistent store (503 otherwise) |
| Chat history (RFC BE) — History node | v1.20 | Search is title-only; Related is the semantic path |
| Memory / document change feed (RFC CD Part C) — Change Event trigger | v1.54 | also needs LOOMCYCLEMEMORYCHANGESENABLED=1 + a changesubscriptions: yaml entry |
| Runnable-agent discovery (RFC BY) | v1.51 | Run → List Runnable Agents; agent dropdown fallback |
| Chunked-graph Documents (RFC AK) off-run | v1.4 | Document node — also needs LOOMCYCLESQLMEMENABLED=1 |
| Document tags / links / history / canvas (RFC BS) | v1.46 | Document → Add Tags / Backlinks / History / Export Canvas |
| Document image assets (RFC BO) | v1.30 | Document → Set Asset / Get Asset |
| Verified writes / fact tier (RFC CC) | v1.54 | Fact node — source spans, verdicts, Verbatim Answer |
| Remote document sources (RFC CE) | v1.54 | Document Source node; Document → Set Remote / Sync / Diff Remote |
| Memory Backend (RFC I) | v0.15 | Memory Backend action node |
| Interruption (human-in-the-loop) | v0.8.16 | Interruption node + Interrupt Pending trigger; resolve needs the consumer-MCP backend |
| Snapshot backup / restore | v0.8.17 | Snapshot action node |
| Operator Token (RFC L multi-tenant auth) | v0.17 | Operator Token node (get/list/retire); /v1/_me credential test |
| Inline code-js code_body + MCP tool auto-discovery | v0.20 | Agent Definition JS editor; MCP Server discover toggle |
| Non-secret metadata channel | v0.21 | Metadata (JSON) on Run / Schedule / Webhook |
| Channel fan-in / fan-out (RFC S) | v0.25 | Channel Await / Broadcast |
| Per-run sampling override | v0.28 | Run → Spawn → Sampling (JSON) |
| Per-run / mid-run compaction | v0.32 | Run → Spawn → Compaction (JSON); Run → Compact |
| Batch spawn (RFC Y) | v0.33 | Run → Spawn Batch |
If you’re on older loomcycle, the unaffected nodes still work; the gated ones surface a clean NodeApiError("Requires loomcycle vX.Y").
n8n version compatibility
1.82.0 (cluster-node API stability threshold)2.22.1 (self-hosted Docker)supplyData() and execute() so they work across older modes too)@loomcycle/client (bundled, not a runtime dependency)
@loomcycle/client (^1.55.0) is bundled into the published nodes at build time (esbuild), so the package ships with zero runtime dependencies — the requirement for n8n Cloud verification. It’s a devDependency here, not a peer/runtime dep. The adapter tracks loomcycle’s minor version; consuming a new wire method bumps the bundled version. n8n-workflow is the only peer; @n8n/ai-node-sdk (used by the Chat Model) is provided by the n8n host at runtime.
Which credential do I need?
Most nodes work with any bearer, but the scope matters for some:
runs: / channel: user token reaches the tenant’s Library, Documents and Memory over HTTP with no new scope and no re-mint — which is what makes the Document, Fact and Memory nodes usable from a delegated per-user credential. Two caveats: an isolated token is still confined to its own user scope, and the carve-out is HTTP-only, so gRPC / MCP parity is deferred upstream.Known upstream gaps
Some substrate operations have no @loomcycle/client method yet, so no node can expose them — this package never hand-rolls a wire call (see CLAUDE.md “Adapter conformance”). The ones you are most likely to notice:
promote / retire / verify. The adapter wraps 7 of the substrate’s 10 TeamDef ops. The practical consequence, verified against a live v1.55: a Fork lands unpromoted, so name-addressed operations (Run by name, Render Diagram) keep resolving to the previously active version. Reach a fork by the def_id it returns — Run accepts one — or promote it via the loomcycle CLI / Web UI / MCP.render_diagram overlay preview and format. The substrate can syntax-check an unsaved graph and render it without persisting, and emit d2 as well as Mermaid; the adapter’s wrapper takes neither.run interruptoncap. The substrate can ask a human what to do when a state hits its iteration cap; the adapter’s runTeam does not expose it.credentialDef and evaluation exist as MCP meta-tools with no adapter method at all.Verified deployments
The integration has been smoke-tested end-to-end against the following configuration:
| Surface | What was validated |
|—|—|
| Action node — Run → Spawn | Picks an agent from the library dropdown (yaml-static + dynamic AgentDef entries, source-tagged), spawns via runStreaming, drains the final text + usage + stopReason into the workflow output |
| Action node — Channel → List | Lists declared channels (read-only credential smoke test) |
| Trigger — Run Completed (polling) | Workflow active → n8n calls poll() on the Poll Times schedule → new terminal-state runs emit, deduped via workflow static data |
| Cluster sub-node — Chat Model inside n8n AI Agent | LoomCycle Chat Model wired to the AI Agent’s Chat Model slot; the agent’s LLM calls route through loomcycle’s gateway (provider routing + per-user quota + single audit log) |
| Network path | TrueNAS-hosted n8n Docker → direct IP to loomcycle (Tailscale MagicDNS bypassed) → sub-second round-trips |
> v3.0.0 note: triggers moved from SSE-push to n8n’s polling framework (n8n Cloud bans in-node timers), so detection latency is the configured poll interval rather than near-instant.
Troubleshooting
Authentication failed after credential test
The bearer doesn’t resolve to a valid principal. Verify with curl against the same endpoint the credential test uses:
curl -H "Authorization: Bearer " http://127.0.0.1:8787/v1/_me
Expect a principal JSON ({"tenantid":"…","subject":"…","scopes":[…],…}). A 401 means the token is invalid/expired; a 404 means the deployment is older than v0.17 (no /v1/me). Under v0.17 multi-tenant auth, also check the token has the scopes for the operations your workflow calls — a missing scope surfaces as a 403 at runtime even though the credential test (which only needs an authenticated principal) passes.
Channel not declared on a Publish
The channel must exist in loomcycle’s channels: yaml block before the publish lands. Declare it operator-side and restart loomcycle. (Dynamic channel creation isn’t supported in the substrate today.)
MCPServerDef ops return “endpoint unknown”
You’re on a loomcycle older than v0.9.2 (PR #177). Upgrade the substrate.
Run Completed / Channel Message trigger isn’t firing
Both are polling triggers — they only fire when the workflow is Active (production), on the schedule set by the node’s Poll Times. In the editor, use Fetch Test Event to run one poll() manually. Detection latency is the poll interval (there’s no SSE push as of v3.0.0).
MCP Server node says “Required env vars on loomcycle: …”
That’s the env-var-mirror hint, not an error. Set the listed env vars on the loomcycle deployment (not on n8n). Restart loomcycle so they’re in scope. The MCP server will then authenticate when an agent invokes it.
LoomCycle Chat Model doesn’t appear in n8n’s AI Agent picker
n8n’s cluster-node API stabilised at 1.82.0. Older n8n versions won’t show the Chat Model sub-node. Upgrade n8n.
Filing issues / contributing
@loomcycle/client.CLAUDE.md for development conventions + the 8 locked design constraints.License
MIT. See LICENSE.
