update

2026-07-28 07:12:13 +07:00
parent 367ebc1c7f
commit 1e5f7b8ff2
29 changed files with 6134 additions and 0 deletions
@@ -0,0 +1,179 @@
+# 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.