# Julia Implementation - AgentCore

This directory contains a Julia reimplementation of the `@earendil-works/pi-agent-core` package.

## Project Structure

```
julia_implementation/
├── src/
│   ├── AgentCore.jl           # Main module entry point
│   ├── types.jl               # Core type definitions
│   ├── stream_fn.jl           # Stream function utilities
│   ├── agent_loop.jl          # Low-level agent loop
│   ├── agent.jl               # High-level Agent struct
│   ├── harness_types.jl       # Extended types for AgentHarness
│   ├── messages.jl            # Custom message types
│   ├── system_prompt.jl       # System prompt formatting
│   ├── skills.jl              # Skill loading and formatting
│   ├── prompt_templates.jl    # Prompt template handling
│   ├── agent_harness.jl       # AgentHarness implementation
│   │
│   ├── session/
│   │   ├── session.jl         # Session class
│   │   ├── jsonl_storage.jl   # JSONL storage
│   │   ├── jsonl_repo.jl      # JSONL repository
│   │   ├── memory_storage.jl  # In-memory storage
│   │   ├── memory_repo.jl     # In-memory repository
│   │   └── repo_utils.jl      # Repository utilities
│   │
│   ├── tools/
│   │   ├── index.jl           # Tool exports
│   │   ├── bash.jl            # Bash execution tool
│   │   ├── read.jl            # File read tool
│   │   ├── write.jl           # File write tool
│   │   ├── edit.jl            # File edit tool
│   │   ├── edit_diff.jl       # Diff computation
│   │   ├── image.jl           # Image utilities
│   │   ├── path_utils.jl      # Path resolution
│   │   └── file_mutation_queue.jl  # File mutation serialization
│   │
│   ├── compaction/
│   │   ├── compaction.jl      # Context compaction
│   │   ├── utils.jl           # Compaction utilities
│   │   └── branch_summarization.jl  # Branch summarization
│   │
│   ├── utils/
│   │   ├── truncate.jl        # Output truncation
│   │   └── shell_output.jl    # Shell output capture
│   │
│   ├── proxy.jl               # Proxy stream function
│   └── utils.jl               # Utility functions
│
├── test/
├── Project.toml
├── Manifest.toml
└── README.md
```

## Key Features

### Core Architecture

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

1. **Low-level (agent_loop.jl)**: Pure agent loop logic that works with `AgentMessage[]`
2. **High-level (agent.jl)**: Stateful wrapper with event streaming and queueing
3. **Harness (agent_harness.jl)**: Session persistence, resource management, hooks
4. **Session (session/)**: Conversation history with compaction and branching
5. **Tools (tools/)**: Built-in execution tools (bash, read, write, edit)

### Julia-Specific Features

- **Type system**: Uses Julia's parametric types for type-safe tool definitions
- **Multiple dispatch**: Extensible via multiple dispatch for custom message types
- **Async primitives**: Leverages Julia's `@async` and `@spawn` for concurrent operations
- **Error handling**: Julia exceptions with typed error codes

## Building

```julia
using Pkg
Pkg.activate("julia_implementation")
Pkg.instantiate()
```

## Usage Example

```julia
using AgentCore

# Create an agent
agent = Agent()

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

# Run a prompt
prompt(agent, "Hello, world!")
```

## Compatibility

This implementation aims for API compatibility with the TypeScript version while providing idiomatic Julia abstractions.

## Status

This is an active implementation. Core functionality is in place, with ongoing work on:

- Complete tool implementations
- Full session repository functionality
- Test suite

## License

MIT