186 lines
7.4 KiB
Markdown
186 lines
7.4 KiB
Markdown
---
|
|
title: Core Agent
|
|
description: AI agent orchestration, Claude Code plugins, and lifecycle management for the Host UK platform — a polyglot Go + PHP repository.
|
|
---
|
|
|
|
# Core Agent
|
|
|
|
Core Agent (`forge.lthn.ai/core/agent`) is a polyglot repository containing **Go libraries**, **CLI commands**, **MCP servers**, and a **Laravel PHP package** that together provide AI agent orchestration for the Host UK platform.
|
|
|
|
It answers three questions:
|
|
|
|
1. **How do agents get work?** -- The lifecycle package manages tasks, dispatching, and quota enforcement. The PHP side exposes a REST API for plans, sessions, and phases.
|
|
2. **How do agents run?** -- The dispatch and jobrunner packages poll for work, clone repositories, invoke Claude/Codex/Gemini, and report results back to Forgejo.
|
|
3. **How do agents collaborate?** -- Sessions, plans, and the OpenBrain vector store enable multi-agent handoff, replay, and persistent memory.
|
|
|
|
|
|
## Quick Start
|
|
|
|
### Go (library / CLI commands)
|
|
|
|
The Go module is `forge.lthn.ai/core/agent`. It requires Go 1.26+.
|
|
|
|
```bash
|
|
# Run tests
|
|
core go test
|
|
|
|
# Full QA pipeline
|
|
core go qa
|
|
```
|
|
|
|
Key CLI commands (registered into the `core` binary via `cli.RegisterCommands`):
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `core ai tasks` | List available tasks from the agentic API |
|
|
| `core ai task [id]` | View or claim a specific task |
|
|
| `core ai task --auto` | Auto-select the highest-priority pending task |
|
|
| `core ai agent list` | List configured AgentCI dispatch targets |
|
|
| `core ai agent add <name> <host>` | Register a new agent machine |
|
|
| `core ai agent fleet` | Show fleet status from the agent registry |
|
|
| `core ai dispatch watch` | Poll the PHP API for work and execute phases |
|
|
| `core ai dispatch run` | Process a single ticket from the local queue |
|
|
|
|
### PHP (Laravel package)
|
|
|
|
The PHP package is `lthn/agent` (Composer name). It depends on `lthn/php` (the foundation framework).
|
|
|
|
```bash
|
|
# Run tests
|
|
composer test
|
|
|
|
# Fix code style
|
|
composer lint
|
|
```
|
|
|
|
The package auto-registers via Laravel's service provider discovery (`Core\Mod\Agentic\Boot`).
|
|
|
|
|
|
## Package Layout
|
|
|
|
### Go Packages
|
|
|
|
| Package | Path | Purpose |
|
|
|---------|------|---------|
|
|
| `lifecycle` | `pkg/lifecycle/` | Core domain: tasks, agents, dispatcher, allowance quotas, events, API client, brain (OpenBrain), embedded prompts |
|
|
| `loop` | `pkg/loop/` | Autonomous agent loop: prompt-parse-execute cycle with tool calling against any `inference.TextModel` |
|
|
| `orchestrator` | `pkg/orchestrator/` | Clotho protocol: dual-run verification, agent configuration, security helpers |
|
|
| `jobrunner` | `pkg/jobrunner/` | Poll-dispatch engine: `Poller`, `Journal`, Forgejo source, pipeline handlers |
|
|
| `plugin` | `pkg/plugin/` | Plugin contract tests |
|
|
| `workspace` | `pkg/workspace/` | Workspace contract tests |
|
|
|
|
### Go Commands
|
|
|
|
| Directory | Registered As | Purpose |
|
|
|-----------|---------------|---------|
|
|
| `cmd/tasks/` | `core ai tasks`, `core ai task` | Task listing, viewing, claiming, updating |
|
|
| `cmd/agent/` | `core ai agent` | AgentCI machine management (add, list, status, setup, fleet) |
|
|
| `cmd/dispatch/` | `core ai dispatch` | Work queue processor (runs on agent machines) |
|
|
| `cmd/workspace/` | `core workspace task`, `core workspace agent` | Isolated git-worktree workspaces for task execution |
|
|
| `cmd/taskgit/` | *(internal)* | Git operations for task branches |
|
|
| `cmd/mcp/` | Standalone binary | MCP server (stdio) with marketplace, ethics, and core CLI tools |
|
|
|
|
### MCP Servers
|
|
|
|
| Directory | Transport | Tools |
|
|
|-----------|-----------|-------|
|
|
| `cmd/mcp/` | stdio (mcp-go) | `marketplace_list`, `marketplace_plugin_info`, `core_cli`, `ethics_check` |
|
|
| `google/mcp/` | HTTP (:8080) | `core_go_test`, `core_dev_health`, `core_dev_commit` |
|
|
|
|
### Claude Code Plugins
|
|
|
|
| Plugin | Path | Commands |
|
|
|--------|------|----------|
|
|
| **code** | `claude/code/` | `/code:remember`, `/code:yes`, `/code:qa` |
|
|
| **review** | `claude/review/` | `/review:review`, `/review:security`, `/review:pr` |
|
|
| **verify** | `claude/verify/` | `/verify:verify`, `/verify:ready`, `/verify:tests` |
|
|
| **qa** | `claude/qa/` | `/qa:qa`, `/qa:fix` |
|
|
| **ci** | `claude/ci/` | `/ci:ci`, `/ci:workflow`, `/ci:fix`, `/ci:run`, `/ci:status` |
|
|
|
|
Install all plugins: `claude plugin add host-uk/core-agent`
|
|
|
|
### Codex Plugins
|
|
|
|
The `codex/` directory mirrors the Claude plugin structure for OpenAI Codex, plus additional plugins for ethics, guardrails, performance, and issue management.
|
|
|
|
### PHP Package
|
|
|
|
| Directory | Namespace | Purpose |
|
|
|-----------|-----------|---------|
|
|
| `src/php/` | `Core\Mod\Agentic\` | Laravel service provider, models, controllers, services |
|
|
| `src/php/Actions/` | `...\Actions\` | Single-purpose business logic (Brain, Forge, Phase, Plan, Session, Task) |
|
|
| `src/php/Controllers/` | `...\Controllers\` | REST API controllers for go-agentic client consumption |
|
|
| `src/php/Models/` | `...\Models\` | Eloquent models: AgentPlan, AgentPhase, AgentSession, AgentApiKey, BrainMemory, Task, Prompt, WorkspaceState |
|
|
| `src/php/Services/` | `...\Services\` | AgenticManager (multi-provider), BrainService (Ollama+Qdrant), ForgejoService, Claude/Gemini/OpenAI services |
|
|
| `src/php/Mcp/` | `...\Mcp\` | MCP tool implementations: Brain, Content, Phase, Plan, Session, State, Task, Template |
|
|
| `src/php/View/` | `...\View\` | Livewire admin components (Dashboard, Plans, Sessions, ApiKeys, Templates, ToolAnalytics) |
|
|
| `src/php/Migrations/` | | 10 database migrations |
|
|
| `src/php/tests/` | | Pest test suite |
|
|
|
|
|
|
## Dependencies
|
|
|
|
### Go
|
|
|
|
| Dependency | Purpose |
|
|
|------------|---------|
|
|
| `forge.lthn.ai/core/go` | DI container and service lifecycle |
|
|
| `forge.lthn.ai/core/cli` | CLI framework (cobra + bubbletea TUI) |
|
|
| `forge.lthn.ai/core/go-ai` | AI meta-hub (MCP facade) |
|
|
| `forge.lthn.ai/core/config` | Configuration management (viper) |
|
|
| `forge.lthn.ai/core/go-inference` | TextModel/Backend interfaces |
|
|
| `forge.lthn.ai/core/go-io` | Filesystem abstraction |
|
|
| `forge.lthn.ai/core/go-log` | Structured logging |
|
|
| `forge.lthn.ai/core/go-ratelimit` | Rate limiting primitives |
|
|
| `forge.lthn.ai/core/go-scm` | Source control (Forgejo client, repo registry) |
|
|
| `forge.lthn.ai/core/go-store` | Key-value store abstraction |
|
|
| `forge.lthn.ai/core/go-i18n` | Internationalisation |
|
|
| `github.com/mark3labs/mcp-go` | Model Context Protocol SDK |
|
|
| `github.com/redis/go-redis/v9` | Redis client (registry + allowance backends) |
|
|
| `modernc.org/sqlite` | Pure-Go SQLite (registry + allowance backends) |
|
|
| `codeberg.org/mvdkleijn/forgejo-sdk` | Forgejo API SDK |
|
|
|
|
### PHP
|
|
|
|
| Dependency | Purpose |
|
|
|------------|---------|
|
|
| `lthn/php` | Foundation framework (events, modules, lifecycle) |
|
|
| `livewire/livewire` | Admin panel reactive components |
|
|
| `pestphp/pest` | Testing framework |
|
|
| `orchestra/testbench` | Laravel package testing |
|
|
|
|
|
|
## Configuration
|
|
|
|
### Go Client (`~/.core/agentic.yaml`)
|
|
|
|
```yaml
|
|
base_url: https://api.lthn.sh
|
|
token: your-api-token
|
|
default_project: my-project
|
|
agent_id: cladius
|
|
```
|
|
|
|
Environment variables override the YAML file:
|
|
|
|
| Variable | Purpose |
|
|
|----------|---------|
|
|
| `AGENTIC_BASE_URL` | API base URL |
|
|
| `AGENTIC_TOKEN` | Authentication token |
|
|
| `AGENTIC_PROJECT` | Default project |
|
|
| `AGENTIC_AGENT_ID` | Agent identifier |
|
|
|
|
### PHP (`.env`)
|
|
|
|
```env
|
|
ANTHROPIC_API_KEY=sk-ant-...
|
|
GOOGLE_AI_API_KEY=...
|
|
OPENAI_API_KEY=sk-...
|
|
```
|
|
|
|
The agentic module also reads `BRAIN_DB_*` for the dedicated brain database connection and Ollama/Qdrant URLs from `mcp.brain.*` config keys.
|
|
|
|
|
|
## Licence
|
|
|
|
EUPL-1.2
|