steve
dfbc5a42b9
The capstone of the run kernel: run.Executor.Run(ctx, RunnableAgent, inv)
ties model resolution + the tool registry + majordomo's agent loop +
context compaction + run-bounding + step/audit instrumentation into one
path, with every host concern behind the nil-safe run.Ports.
- run/executor.go: New(Config{Registry, Models, Defaults, Ports, Compactor,
ContextTokens, SystemHeader}) + Run -> Result{RunID, Output, Steps, Usage,
Err}. Budget gate (pre-run), model resolve, Audit StartRun/recorder
(satisfies RunTally, stamped on inv.RunState), toolbox build, step observer
(zips tool calls/results -> emitter + recorder.OnStep/OnTool), V10
detached-MaxRuntime context with caller-cancel merged back, compaction wired
from ContextTokens×ratio, audit Close + Budget Commit on a detached cleanup
ctx. Zero Ports = a bounded in-memory run (gadfly's case).
- run/executor_test.go: hermetic end-to-end run against majordomo's fake
provider (hello-world), Budget-rejection (no model call), Audit-port wiring
(StartRun + Close with terminal status/output). All green under -race.
- examples/minimal upgraded to the real "hello, agentic world" (~15 lines:
Configure tiers -> run.New -> Run -> print). README/CLAUDE.md updated.
Remaining P2 follow-ups (incremental): wire Critic/Checkpointer/PaletteSource/
Delivery into the loop, multi-phase Pipelines, and the no-tools direct path.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
70 lines
3.3 KiB
Markdown
70 lines
3.3 KiB
Markdown
# executus
|
||
|
||
> ⚠️ **This project is vibe-coded.**
|
||
> executus is written almost entirely by an AI coding agent (Claude), with a
|
||
> human steering at the design and review level rather than typing the code.
|
||
> That's a deliberate choice, stated up front — the same way [gadfly] is. Read
|
||
> the code before you depend on it, pin a version, and file issues if something
|
||
> looks off. It is offered as-is.
|
||
|
||
[gadfly]: https://gitea.stevedudenhoeffer.com/steve/gadfly
|
||
|
||
A **batteries-included base for building LLM agent harnesses in Go.** Import it,
|
||
do a little wiring, and you have agentic capabilities: a bounded run loop, a tool
|
||
registry with a suite of common tools, context compaction, config-driven model
|
||
tiering and failover, structured output, and parallel fan-out — with sensible
|
||
defaults so a brand-new project is agentic with almost no setup, and pluggable
|
||
seams so a serious host can swap in its own storage, config, delivery, and tools.
|
||
|
||
executus sits **strictly above** [majordomo] — the lean LLM substrate (agent
|
||
loop, canonical `llm` types, providers, media normalization, model parsing /
|
||
failover / tiering). majordomo stays the substrate; executus is the opinionated,
|
||
batteries-included layer on top. executus requires **no changes to majordomo**.
|
||
|
||
[majordomo]: https://gitea.stevedudenhoeffer.com/steve/majordomo
|
||
|
||
## Status
|
||
|
||
Early. Being extracted, phase by phase, from the agent layer of [mort] (a Discord
|
||
bot) — mort and gadfly are the first two consumers (heavy and light). See
|
||
`CLAUDE.md` for the architecture and the extraction roadmap (P0–P6).
|
||
|
||
[mort]: https://gitea.stevedudenhoeffer.com/steve/mort
|
||
|
||
**Available today:**
|
||
|
||
- `run/` — **executus is runnable.** `run.Executor` ties model resolution, the
|
||
tool registry, majordomo's agent loop, context compaction, run-bounding, and
|
||
step/audit instrumentation into one `Run(ctx, RunnableAgent, inv) Result`, with
|
||
every host concern behind a nil-safe `run.Ports` (Audit/Budget/Critic/
|
||
Checkpointer/PaletteSource/Delivery). See `examples/minimal`.
|
||
- `model/` — config-driven tier resolution + failover over majordomo, with
|
||
pluggable `UsageSink`/`TraceSink` and `GenerateWith[T]` structured output.
|
||
- `tool/` — the tool registry + 3-stage permission model + SSRF guard.
|
||
- `compact/` — the per-run context compactor.
|
||
- `lane/` — bounded worker pool with fair-share queueing (run- and
|
||
provider-concurrency).
|
||
- `fanout/` — programmatic N×M swarm with bounded global + per-key concurrency.
|
||
- `config/`, `deliver/`, `identity/` — host seams (config / output / identity),
|
||
each with a shipped default.
|
||
- `dispatchguard/`, `pendingattach/` — run-safety primitives.
|
||
|
||
## Design
|
||
|
||
Two tiers in one module (`go.mod` = majordomo + stdlib only):
|
||
|
||
- **Core** — everything a light host needs to be agentic: run loop, tool
|
||
registry + common tools, model resolution, compaction, lanes, fan-out,
|
||
structured output. No persistence, no scheduling.
|
||
- **Batteries** (opt-in sibling packages) — persona/agent nouns, saved skills,
|
||
audit, run-critic, scheduling, budgets, checkpointing. Each is nil-safe and
|
||
ships a default, so you add only what you use.
|
||
|
||
Persistence that needs a real database lives in a **separate** nested module
|
||
(`contrib/store`, pure-Go SQLite) so the core never drags in a DB driver — a
|
||
static-binary host (gadfly) stays static.
|
||
|
||
## License
|
||
|
||
TBD.
|