Skip to content

About

agent harness prototypes in php, typescript and python

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Agent Harness

Warning

This repository is for exploration and planning purposes only. It is not intended for production use. APIs, structure, and documentation may change without notice. Written entirely using Claude Code in a few hours, just to try out "what if".

A lightweight, composable framework for building LLM-powered agents. Implemented across Python, TypeScript, PHP, and Go with trait/mixin/embedding-based composition.

Harness has two distinctive features.

The virtual shell replaces per-query tools with an in-memory filesystem and shell interpreter — you mount context as files and let the model explore with Unix commands (grep, cat, find, jq) it already knows. Register custom commands (deploy, validate, etc.) that compose naturally with pipes and control flow. Every command is pure emulation with no security risk. The shell backend is swappable via a driver architecture — the builtin pure-language shell works out of the box, switch to bashkit for full POSIX compliance, or use OpenShell for secure sandboxed execution with policy enforcement.

The inline event system uses a convention-based YAML format where the last field in an event block is automatically streamable — no special syntax or schema annotations needed. Events are buffered by default; streaming is opt-in per field, and the parser handles framing, async iteration, and backpressure transparently.

Along with typical agentic features:

  • tools
  • skills
  • hooks
  • middleware
  • slash commands

For now, mcp support has been deferred, as integrations would be better implemented with a combination of a custom skill and cli command.

The ultimate aim is for this work to be integrated into an event driven/sourced workflow package, which would then allow durable, complex multi-agent and multi-step orchestration.

Documentation

Language Guides

Cross-Cutting Guides

  • Skills — Mountable capability bundles (tools + middleware + hooks + commands + instructions)
  • Slash Commands — Design pattern for slash-style commands via skills or custom shell commands
  • Middleware — Sequential Pre/Post transformation pipeline around every LLM request
  • Hooks — Lifecycle events, handler registration, concurrency, and panic isolation
  • LLM Providers — Which providers each language supports today, how to configure model strings, API keys, base URLs, streaming, retries, and the per-language asymmetry
  • Tools — LLM-callable functions with auto-generated JSON schemas, cross-language registration, and error handling
  • Exec Tool — Auto-registered shell tool the LLM uses to run any virtual-shell command, with an opt-in Bash alias for Claude Code prompt portability
  • File Tools — Built-in Read/Write/Edit/Glob/Grep mirroring Claude Code's surface, over the swappable FilesystemDriver
  • Virtual Filesystem — How the in-memory VFS is used and implemented: mounting files, lazy files, per-agent isolation via clone, and host-owns sync for external drivers
  • Events — Inline YAML events emitted by the LLM, parser + message bus, streaming fields

Shell Guides

  • Virtual Bash — Supported syntax, commands, and limitations
  • Bashkit — POSIX shell driver setup, usage, and custom commands
  • OpenShell — Secure sandboxed execution with gRPC, policy enforcement, and streaming

Architecture Decision Records

Design decisions are documented in docs/adr/.

Notes

Streamed events currently assumes last field is streamed - this needs to be reviewed and api adjusted accordingly.

Need to think further about the message bus and whether there should be any convensions re. emtting events vs commands (and tools). Message bus will be a separate package.

Virtual fs/shell could be extracted into separate packages - in particular, the virtual fs/shell could be a high performance core, say in rust with extensibility in the client languages. The bashkit integration uses the bashkit PyO3 package for Python (in-process, stateful, with custom command support) and the bashkit CLI for TypeScript/PHP (stateless subprocess).

Need to add support for LLM gateways including rate limits, retries, observability, etc cf middleware.

Need to add support for open responses ie. create common classes or use standard libraries.

Consider implementing something like mcpporter or mcp2cli for mcp support.

Consider implementing a todo tool (cf. tick) and a memory tool.

Consider building an event driven workflow layer.

Consider implementing or integration something like context mode for better context management.

About

agent harness prototypes in php, typescript and python

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages