@openreachtech/mentsu-agent-loop-core

Reusable agent-loop framework (core) — the iteration engine, composition primitives and progress seam behind an LLM agent, with zero runtime dependencies.

Table of Contents

• Concept
• Installation
• Features
• API
• How the loop works
• Related Packages
• Contribution
• License
• Developer
• Copyright

Concept

@openreachtech/mentsu-agent-loop-core is the set of base classes that factors out the iteration of an LLM agent. An application writes only its own domain actions and loops; iteration, stop conditions, context compression, progress notification and parallel/sequential composition come from the core.

The design rests on four pillars.

• Zero dependencies. The core imports no AI, DB, queue or transport package. Every business dependency arrives through context, an opaque DI slot the core never inspects.
• Shared machinery is not rewritten per app. The iteration body (tail-recursive iterate), the progress seam (emitProgress) and composition (parallel / sequential) live here. An application implements a handful of abstract hooks.
• Every member is an instance method. No pure functions and no static-only classes are exported, so an application can always work around a defect by extends plus a method override — nothing is truly final.
• Transport-agnostic progress. Progress is delivered by calling onProgress(event). Whether that becomes Redis, GraphQL or SSE is decided outside the core.

Redis-backed job execution (horizontal scaling, retries) and GraphQL request/subscription handling are added as separate adapter packages. The dependency direction is one-way: adapters import the core, never the reverse. See Related Packages.

Installation

Requires Node.js 20.x (the version the CI builds against).

npm install @openreachtech/mentsu-agent-loop-core

It is an ES module ("type": "module"); import it with ESM import syntax.

Features

(1) Actions and the registry

Usage of actions

(2) AI-driven loop

Usage of ai-driven-loop

(3) Procedural loop

Usage of procedural-loop

(4) Parallel composition (fan-out / fan-in)

Usage of parallel-composition

(5) Sequential pipeline

Usage of sequential-pipeline

(6) Context compression

Usage of context-compression

(7) Progress notification

Usage of progress

(8) Execution-mode runners

Usage of runners

(9) Contract testing kit

Usage of contract-testing

API

API references

How the loop works

The Runnable contract

Every composable unit satisfies the same two-member contract:

static create({ context })   +   async run({ input, onProgress })

BaseAgentLoop, BaseCompositeAgent, BaseAgentPipeline and BaseActionStage all satisfy it, which is why a pipeline stage may itself be a pipeline, a composite may fan out into loops, and any of them can be dropped into another.

The iteration body

run() builds the initial state and hands it to iterate(), which recurses on itself instead of looping:

1. isComplete({ state, iteration }) — if true, return buildResult({ state }).
2. iteration >= maxIterations — if true, return buildResult({ state }). This is the safety bound (default 10).
3. compressIfNeeded({ state, iteration }) — compress the working context when shouldCompress says so.
4. advanceState({ state, iteration }) — produce the next state.
5. emitProgress() — fire the progress event for this iteration.
6. Recurse with iteration + 1.

State is never mutated: each hook returns a new state, so an iteration is reproducible from its inputs.

Three separate concepts

| concept | what it holds | lifetime | example | | :-- | :-- | :-- | :-- | | state (iteration state) | per-step output, history, score | one run; replaced immutably each iteration | state.history / state.score | | context (shared dependencies) | AI / search / DB clients | the whole run; read-only | context.elasticsearchClient | | working context (compression target) | the accumulated text handed to the AI | grows with iterations, then shrinks | the summary written back into state.history |

Related Packages

| package | role | | :-- | :-- | | @openreachtech/mentsu-agent-loop-core | this package — the core, zero dependencies | | @openreachtech/mentsu-agent-loop-renchan-job | Redis execution adapter: runs a loop as a renchan-job / BullMQ job, with horizontal scaling and progress publishing | | @openreachtech/mentsu-agent-loop-graphql | GraphQL resolver bases: request Mutation and progress Subscription (planned) |

The dependency direction is one-way — the core imports none of these.

Contribution

Bug reports, feature requests, and code contributions are welcome.

Feel free to contact us through GitHub Issues.

git clone https://github.com/openreachtech/mentsu-agent-loop-core.git
cd mentsu-agent-loop-core
npm install
npm run lint
npm test

License

This project is released under the Apache License 2.0.

For more details, please see in the LICENSE file.

Developer

Open Reach Tech Inc.

Copyright

© 2026 Open Reach Tech Inc.