@belarusian/agent-system

What Is This?

A self-contained TypeScript agent platform: LLM client, tool system, agent loop with dual-model A* search, and a context-transfer bridge. Extract the pieces you need or use them all together.

Built on Effect v4, runs against any OpenAI-compatible LLM server (llama.cpp, vLLM, Ollama, etc.).

Packages

Package	Purpose
`@belarusian/harness`	LLM client + agent loop (self-contained)
`@belarusian/tools`	16 built-in tools: read, write, edit, shell, glob, grep, webfetch, etc.
`@belarusian/agents`	Agent service with skills, subagents, and built-in presets
`@belarusian/bridge`	Context-aware MoE↔dense conversation bridge
`@belarusian/cli`	CLI for running agents standalone or as orchestrator workers

Installation

From source

pnpm install
pnpm build

As a third-party dependency

Packages are published to GitHub Packages under @belarusian scope. Add auth token:

echo "//npm.pkg.github.com/:_authToken=ghp_YOUR_TOKEN" >> ~/.npmrc
echo "@belarusian:registry=https://npm.pkg.github.com/" >> ~/.npmrc

Then install:

# Just the agent loop
npm install @belarusian/harness effect

# Agent loop + tools
npm install @belarusian/harness @belarusian/tools effect

# Full stack (agents)
npm install @belarusian/agents @belarusian/harness effect

Quick Start

CLI

opencode-agent run \
  --prompt "Build a REST API for user auth" \
  --model "qwen3-coder" \
  --url "http://localhost:8080/v1"

SDK

import { runAgent } from "@belarusian/harness";
import * as Effect from "effect/Effect";

const result = await Effect.runPromise(
  runAgent({
    config: { baseUrl: "http://localhost:8080/v1", model: "qwen3-coder" },
    messages: [{ role: "user", content: "Build a REST API" }],
    maxSteps: 5,
  }),
);

Architecture

packages/
├── harness/     ── @belarusian/harness (LLM client, agent loop, tool execution)
├── tools/       ── @belarusian/tools   (16 file/shell/web/search tools)
├── agents/      ── @belarusian/agents  (AgentService, SkillService, SubagentService)
└── bridge/      ── @belarusian/bridge  (MoE↔dense context transfer)

apps/
└── cli/         ── @belarusian/cli    (standalone agent runner via `opencode-agent`)

Two Execution Paths

Path	Returns	Use Case
`runAgent()`	`AgentLoopResult`	"Call it, get a result" — simple synchronous usage
`streamAgent()`	`Stream<LLMEvent>`	Real-time streaming — UI updates, progress indicators

A* Dual-Model Bridge

Built-in A* search: MoE explores breadth-first, then hands off to a dense model for deep implementation. See AGENTS.md for full usage.

Packages In Detail

@belarusian/harness

Self-contained LLM client — bundles all types (schema, events, client, tool execution, agent loop). Exports:

LLMClient, LLMClientLayer — streaming LLM client
runAgent(), streamAgent() — agent loop with tool execution
ToolExecutor, makeDynamicTool() — tool system
ProviderService — multi-provider management
A* bridge: mode-switching between MoE (explore) and dense (produce) models

@belarusian/tools

16 built-in tools using the harness tool system:

Files: read, write, edit, truncate, applyPatch
Shell: shell (execa-based command execution)
Search: glob, grep
Web: websearch, webfetch
Git: repoClone, repoOverview
Meta: task, todo, question, invalid, lsp