FlossWare's provider-neutral agent execution/orchestration stack built around a worker / arbiter architecture.
A worker is any capable unit of work. It is not synonymous with an LLM. A worker may be deterministic code, a CLI, MCP capability, another agent, a local model, a hosted model, a test runner, or a composite worker.
Work
-> capability matching
-> Workers
-> deterministic tool
-> CLI
-> MCP capability
-> agent
-> model
-> composite worker
-> Arbiter
-> collect evidence
-> detect disagreement
-> synthesize
-> Result
The arbiter is the synthesis boundary. Model-based consensus is one possible synthesis implementation, not a prerequisite for the architecture.
Task -> isolated worktree -> Worker -> Tests -> Hard gates -> Arbiter -> Accept/Reject -> Apply
- Each run can execute in a disposable git worktree.
- A coding worker investigates, plans, changes files, and runs tests.
- Deterministic hard gates can reject failures regardless of model output.
- An independent arbiter reviews the proposed result.
- Rejection feeds actionable feedback back to the worker for another iteration.
- Accepted changes can be applied to the primary tree.
Provider, model, vendor, hosting topology, authentication mechanism, and pricing are routing and policy inputs, not architectural defaults. The runtime does not require or prefer a particular provider or pricing tier.
See personal_agent/capability.py for the generic capability-worker contract and personal_agent/arbiter.py for the arbiter implementation.
agent-ai is the execution/orchestration layer. Installation, profiles, provider/model discovery, diagnostics, and Crush provisioning belong to the separate agent-setup control plane.
For normal installation, use the canonical agent-setup bootstrap documented at:
https://github.com/FlossWare/agent-setup
For development:
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest -qcd /path/to/your/git/repository
pa --investigate "What are the main components?" --repo .
pa "Fix the failing test in test_auth.py" --repo . --commands pytest --max-iter 3Do not use --commit on the first dogfood run. Review the generated diff and verification results first.
pa --investigate "What are the main components?" --repo .
pa "Fix the failing test in test_auth.py" --repo . --commands pytest --max-iter 3
pa -v "Summarize the security model" --repo . --jsonimportasynciofrompersonal_agentimportCapabilityArbiter, FunctionWorker, Workasyncdefmain():
workers= [
FunctionWorker("static-check", {"inspect"}, lambdawork: "static evidence"),
FunctionWorker("tests", {"inspect", "verify"}, lambdawork: "tests evidence"),
]
result=awaitCapabilityArbiter(workers).execute(
Work("inspect repository", frozenset({"inspect"}))
)
print(result.conclusion)
asyncio.run(main())importasynciofrompersonal_agentimportCodingAgentfrompersonal_agent.typesimportTaskasyncdefmain():
repo="/path/to/git/repository"agent=CodingAgent(repo, max_iterations=3)
task=Task(
description="Fix the failing test in test_auth.py",
repo_path=repo,
commands=["pytest"],
max_iterations=3,
)
result=awaitagent.run(task)
print(result.decision, result.iterations)
# Review result.final_diff and result.arbiter_decisions before any commit.asyncio.run(main())Configure provider credentials in the parent process via agent-setup or an OS secret store. Workers remain credential-free. Integration coverage lives under tests/.
Credentials belong to the authentication boundary and must not be embedded in source, generated configuration, images, or Git history.
- command policy and filesystem confinement (
docs/COMMAND-POLICY.md) - credential isolation and secret redaction (
docs/SECURITY.md) - deterministic verification gates
- disposable worktrees
- independent arbitration
See docs/SECURITY.md for the threat model and credential boundaries.
pytest -qThe repository contains focused tests for worker contracts, arbitration, routing, security, verification, repository operations, and the end-to-end agent loop. Coverage is measured in CI rather than represented by a hand-maintained percentage in this README.
See docs/TROUBLESHOOTING.md for common installation, credential, worktree, router, and rejection-loop failures.
| Limitation | Notes |
|---|---|
| Python 3.11+ | Required by requires-python. |
| Fedora Tier-1 | Primary dogfood path via agent-setup; other platforms are best-effort. |
--max-iter default 3 | Bounds cost and runaway reject loops. |
Git HEAD dependency pins | Dogfood policy; use release tags or immutable SHAs for reproducible releases. |
Dependency policy is documented in docs/VERSIONING.md.
- agent-ai: agent execution, workers, arbitration, iteration, and engineering workflow
- agent-setup: installation, profiles, configuration, discovery, diagnostics, and external-agent setup
- model-router-ai: provider/account/model routing and selection
- consensus-ai: reusable consensus and arbitration strategies
- crush-demo: integration and acceptance harness, not an architecture layer
Existing capability libraries should be reused rather than duplicated. agent-ai remains provider-neutral and should not absorb setup or provider-specific concerns.
MIT