# AgentCore.jl - Julia Implementation of Pi Agent Core

A Julia reimplementation of the `@earendil-works/pi-agent-core` package, providing a stateful agent framework for LLM interactions.

## Overview

This package provides:
- Low-level `agentLoop` for stateful LLM interactions with tool execution
- High-level `Agent` struct with state management, event streaming, and queueing
- `AgentHarness` for session persistence, resource management, and extension hooks
- Built-in tools for file operations (read, write, edit) and bash execution
- Session management with JSONL-based storage, compaction, and branch navigation

## Architecture

The Julia implementation follows the same layered architecture as the TypeScript version:

```
┌─────────────────────────────────────────────────────────────────────┐
│                            AgentHarness                              │
│              (Session persistence, resource management)              │
└─────────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────────┐
│                              Agent                                 │
│              (State management, event streaming, queueing)           │
└─────────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────────┐
│                          AgentLoop                                 │
│              (Low-level loop, tool execution)                        │
└─────────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────────┐
│                            Session                                 │
│              (Conversation history, compaction, branching)           │
└─────────────────────────────────────────────────────────────────────┘
```

## Installation

```julia
using Pkg
Pkg.add("AgentCore")
```

## Quick Start

```julia
using AgentCore

# Create an agent with default configuration
agent = Agent()

# Subscribe to events
subscribe(agent) do event, signal
    if event isa MessageEndEvent
        println("Received message: $(event.message)")
    end
end

# Run a prompt
prompt(agent, "Hello, how are you?")
```

## Core Concepts

### Agent

The `Agent` struct provides a high-level interface for interacting with LLMs. It manages:
- Conversation state (messages, tools, system prompt)
- Event streaming and lifecycle management
- Steering and follow-up message queues
- Abort handling

### AgentLoop

The `agentLoop` function implements the core agent loop that:
- Transforms `AgentMessage[]` to `Message[]` at the LLM call boundary
- Executes tool calls (parallel or sequential)
- Emits lifecycle events
- Handles steering and follow-up messages

### AgentHarness

The `AgentHarness` provides:
- Session persistence with JSONL storage
- Resource management (skills, prompt templates)
- Extension hooks system
- Tool execution with context
- Branch navigation and compaction

### Sessions

Sessions track conversation history using a tree-based structure:
- Branch-based history with compaction
- Tree navigation (moveTo, navigateTree)
- Message and metadata persistence

## Built-in Tools

### Bash Tool

Execute shell commands with output capture and truncation.

```julia
bash_tool = createBashTool()
```

### Read Tool

Read files with support for text and images.

```julia
read_tool = createReadTool()
```

### Write Tool

Write content to files with automatic directory creation.

```julia
write_tool = createWriteTool()
```

### Edit Tool

Edit files using exact text replacement.

```julia
edit_tool = createEditTool()
```

## Session Storage

AgentCore supports two session storage backends:

1. **JsonlSessionStorage** - File-based storage using JSONL format
2. **InMemorySessionStorage** - In-memory storage for testing

## Compaction

The compaction system manages context window usage by:
- Summarizing old conversation history
- Retaining recent messages
- Supporting iterative updates to summaries

## Event System

AgentCore uses a rich event system for monitoring and control:

- `AgentStartEvent` / `AgentEndEvent` - Agent lifecycle
- `TurnStartEvent` / `TurnEndEvent` - Conversation turns
- `MessageStartEvent` / `MessageEndEvent` - Message lifecycle
- `ToolExecutionStartEvent` / `ToolExecutionEndEvent` - Tool execution

## Examples

See the `examples/` directory for more detailed examples.

## Differences from TypeScript

While maintaining API compatibility where possible, this Julia implementation:
- Uses Julia's type system for better compile-time guarantees
- Leverages Julia's multiple dispatch for extensibility
- Uses Julia's async primitives for concurrent operations
- Provides more idiomatic Julia error handling

## Contributing

Contributions are welcome! Please see `CONTRIBUTING.md` for details.

## License

MIT

## Acknowledgments

This is a reimplementation of the [Pi Agent Core](https://github.com/earendil-works/pi/packages/agent) package in Julia.