# Specification: AgentCore.jl Technical Contract

This specification defines the precise technical contracts for the AgentCore.jl system, mapping implementation details to requirements and solution design decisions.

## 1. Agent State Types

### 1.1 AgentState

**Requirement Reference**: FR-001 (Agent State Management)

The `AgentState` struct maintains conversation state with the following fields:

| Field | Type | Description | Requirement ID |
|-------|------|-------------|----------------|
| `system_prompt` | `String` | System prompt for the LLM | FR-001 |
| `model` | `Model` | Current model configuration | FR-001 |
| `thinking_level` | `ThinkingLevel` | Thinking mode for LLM | FR-001 |
| `tools` | `Vector{AgentTool}` | Available tools for execution | FR-001 |
| `messages` | `Vector{AgentMessage}` | Conversation history | FR-001 |
| `is_streaming` | `Bool` | Streaming state | FR-004 |
| `streaming_message` | `Union{AgentMessage, Nothing}` | Current streaming message | FR-004 |
| `pending_tool_calls` | `Set{String}` | Active tool call IDs | FR-002 |
| `error_message` | `Union{String, Nothing}` | Current error state | FR-002 |

**Specification ID**: SPEC-1.1

### 1.2 ThinkingLevel Enum

**Requirement Reference**: FR-001

| Value | Description | Use Case |
|-------|-------------|----------|
| `THINKING_OFF` | No thinking mode | Simple Q&A |
| `THINKING_MINIMAL` | Minimal chain of thought | Quick decisions |
| `THINKING_LOW` | Low reasoning effort | Standard operations |
| `THINKING_MEDIUM` | Moderate reasoning | Complex problems |
| `THINKING_HIGH` | High reasoning | Difficult reasoning |
| `THINKING_XHIGH` | Extended reasoning | Multi-step problems |
| `THINKING_MAX` | Maximum reasoning | Critical decisions |

**Specification ID**: SPEC-1.2

### 1.3 ToolExecutionMode Enum

**Requirement Reference**: FR-002

| Value | Description |
|-------|-------------|
| `EXECUTION_SEQUENTIAL` | Execute tools one at a time |
| `EXECUTION_PARALLEL` | Execute tools concurrently |

**Specification ID**: SPEC-1.3

### 1.4 Message Content Types

**Requirement Reference**: FR-001

| Type | Fields | Description |
|------|--------|-------------|
| `TextContent` | `text::String` | Plain text content |
| `ImageContent` | `data::String, mime_type::String` | Base64-encoded image |

**Specification ID**: SPEC-1.4

## 2. Message Types

### 2.1 AgentMessage Union Type

**Requirement Reference**: FR-001

Abstract type for all agent messages. Concrete types include:

| Type | Role | Description |
|------|------|-------------|
| `UserMessage` | user | User input messages |
| `AssistantMessage` | assistant | LLM responses |
| `ToolResultMessage` | toolResult | Tool execution results |

**Specification ID**: SPEC-2.1

### 2.2 UserMessage

**Requirement Reference**: FR-001

| Field | Type | Description | Requirement ID |
|-------|------|-------------|----------------|
| `role` | `String` | Always "user" | FR-001 |
| `content` | `Vector{MessageContent}` | Message content (text, images) | FR-001 |
| `timestamp` | `Timestamp` | Creation timestamp | FR-001 |

**Specification ID**: SPEC-2.2

### 2.3 AssistantMessage

**Requirement Reference**: FR-001, FR-002

| Field | Type | Description | Requirement ID |
|-------|------|-------------|----------------|
| `role` | `String` | Always "assistant" | FR-001 |
| `content` | `Vector{MessageContent}` | Response content | FR-001 |
| `api` | `String` | API identifier | FR-001 |
| `provider` | `String` | LLM provider name | FR-001 |
| `model` | `String` | Model identifier | FR-001 |
| `usage` | `Usage` | Token usage statistics | FR-001 |
| `stop_reason` | `String` | Reason for completion | FR-002 |
| `error_message` | `Union{String, Nothing}` | Error details if failed | FR-002 |
| `timestamp` | `Timestamp` | Response timestamp | FR-001 |

**Specification ID**: SPEC-2.3

### 2.4 ToolResultMessage

**Requirement Reference**: FR-002

| Field | Type | Description | Requirement ID |
|-------|------|-------------|----------------|
| `role` | `String` | Always "toolResult" | FR-002 |
| `tool_call_id` | `String` | ID of tool call | FR-002 |
| `tool_name` | `String` | Name of tool | FR-002 |
| `content` | `Vector{MessageContent}` | Tool result content | FR-002 |
| `details` | `Any` | Tool-specific details | FR-002 |
| `usage` | `Union{Usage, Nothing}` | Tool execution usage | FR-002 |
| `added_tool_names` | `Union{Vector{String}, Nothing}` | Newly available tools | FR-002 |
| `is_error` | `Bool` | Whether tool failed | FR-002 |
| `timestamp` | `Timestamp` | Result timestamp | FR-002 |

**Specification ID**: SPEC-2.4

## 3. Tool Interface

### 3.1 AgentTool

**Requirement Reference**: FR-002, Solution Design SD-002

Tools are defined by the `AgentTool` struct:

| Field | Type | Description | Requirement ID |
|-------|------|-------------|----------------|
| `name` | `String` | Tool identifier | FR-002 |
| `label` | `String` | Human-readable label | FR-002 |
| `description` | `String` | Tool purpose description | FR-002 |
| `parameters` | `Any` | Parameter schema | FR-002 |
| `execute` | `Function` | Tool execution function | FR-002 |
| `prepare_arguments` | `Union{Function, Nothing}` | Argument transformation | FR-002 |
| `execution_mode` | `Union{ToolExecutionMode, Nothing}` | Execution strategy | FR-002, SD-004 |

**Specification ID**: SPEC-3.1

### 3.2 Tool Execution Contract

**Requirement Reference**: FR-002, Solution Design SD-002

The `execute` function signature:
```julia
execute(
    tool_call_id::String,
    arguments::Any,
    signal::Union{Nothing, AbortSignal},
    on_update::Function
)::AgentToolResult
```

**Specification ID**: SPEC-3.2

## 4. Session Storage Interface

### 4.1 SessionTreeEntry

**Requirement Reference**: FR-003

Abstract type for session history entries:

| Type | Description |
|------|-------------|
| `MessageEntry` | Conversation message |
| `ThinkingLevelChangeEntry` | Thinking level change |
| `ModelChangeEntry` | Model configuration change |
| `ActiveToolsChangeEntry` | Tool availability change |
| `CompactionEntry` | History compaction |
| `BranchSummaryEntry` | Branch summary |
| `CustomEntry` | Custom entry type |
| `LabelEntry` | Entry label |
| `SessionInfoEntry` | Session metadata |
| `LeafEntry` | Current session leaf |

**Specification ID**: SPEC-4.1

### 4.2 JsonlSessionStorage Interface

**Requirement Reference**: FR-003, Solution Design SD-003

Required methods:

| Method | Returns | Description |
|--------|---------|-------------|
| `getMetadata()` | `SessionMetadata` | Session metadata |
| `appendEntry(entry)` | `Nothing` | Add history entry |
| `getEntry(id)` | `Union{SessionTreeEntry, Nothing}` | Retrieve entry by ID |
| `findEntries(type)` | `Vector{SessionTreeEntry}` | Find entries by type |
| `getSessionStats()` | `SessionStats` | Session statistics |
| `getEntries(options)` | `Vector{SessionTreeEntry}` | Query entries |

**Specification ID**: SPEC-4.2

### 4.3 SessionStats

**Requirement Reference**: FR-003

| Field | Type | Description |
|-------|------|-------------|
| `message_count` | `Int64` | Number of messages |
| `cached_tokens` | `Int64` | Cached token count |
| `uncached_tokens` | `Int64` | Uncached token count |
| `total_tokens` | `Int64` | Total tokens processed |
| `cost_total` | `Float64` | Total cost |

**Specification ID**: SPEC-4.3

## 5. Event System

### 5.1 Agent Event Types

**Requirement Reference**: FR-004

| Event | Description | Fields |
|-------|-------------|--------|
| `AgentStartEvent` | Agent started | - |
| `AgentEndEvent` | Agent completed | `messages::Vector{AgentMessage}` |
| `TurnStartEvent` | New conversation turn | - |
| `TurnEndEvent` | Conversation turn completed | `message`, `tool_results` |
| `MessageStartEvent` | Message started | `message` |
| `MessageEndEvent` | Message completed | `message` |
| `ToolExecutionStartEvent` | Tool execution started | `tool_call_id`, `tool_name`, `args` |
| `ToolExecutionEndEvent` | Tool execution completed | `tool_call_id`, `tool_name`, `result`, `is_error` |

**Specification ID**: SPEC-5.1

### 5.2 Event Subscription API

**Requirement Reference**: FR-004

```julia
subscribe(agent::Agent, listener::Function)::Function
```

- Returns unsubscription function
- Listener signature: `(event::AgentEvent, signal::AbortSignal) -> Nothing`
- Events broadcast to all subscribers concurrently

**Specification ID**: SPEC-5.2

## 6. API Endpoints

### 6.1 Agent Methods

**Requirement Reference**: FR-001, FR-005

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `prompt(agent, input)` | `input::Union{String, AgentMessage, Vector{AgentMessage}}` | `Nothing` | Start new prompt |
| `continue!(agent)` | - | `Nothing` | Continue from last message |
| `steer(agent, message)` | `message::AgentMessage` | `Nothing` | Queue steering message |
| `followUp(agent, message)` | `message::AgentMessage` | `Nothing` | Queue follow-up message |
| `reset!(agent)` | - | `Nothing` | Clear all state |
| `get_state(agent)` | - | `AgentState` | Get current state |
| `subscribe(agent, listener)` | `listener::Function` | `Function` | Subscribe to events |

**Specification ID**: SPEC-6.1

### 6.2 AgentLoop Functions

**Requirement Reference**: FR-002, Solution Design SD-001

| Function | Parameters | Returns | Description |
|----------|------------|---------|-------------|
| `agentLoop()` | `prompts, context, config, signal, stream_fn` | `EventStream` | Run agent loop |
| `agentLoopContinue()` | `context, config, signal, stream_fn` | `EventStream` | Continue agent loop |
| `streamAssistantResponse()` | `context, config, signal, emit, stream_fn` | `AssistantMessage` | Stream LLM response |

**Specification ID**: SPEC-6.2

## 7. Error Codes

### 7.1 Agent Errors

**Requirement Reference**: FR-001, FR-002

| Code | Description |
|------|-------------|
| `AGENT_BUSY` | Agent already processing |
| `INVALID_MESSAGE_ROLE` | Invalid message role for operation |
| `AGENT_NOT_FOUND` | Session not found |
| `TOOL_NOT_FOUND` | Tool not registered |

**Specification ID**: SPEC-7.1

### 7.2 Tool Errors

**Requirement Reference**: FR-002

| Code | Description |
|------|-------------|
| `EXECUTION_TIMEOUT` | Tool execution timed out |
| `EXECUTION_ABORTED` | Tool execution aborted |
| `TOOL_NOT_SUPPORTED` | Tool not available |
| `INVALID_PARAMETERS` | Tool parameters invalid |

**Specification ID**: SPEC-7.2

## 8. Data Validation Rules

### 8.1 Message Content

**Requirement Reference**: FR-001, FR-002

| Constraint | Rule |
|------------|------|
| `TextContent.text` | Must be non-empty string |
| `ImageContent.data` | Must be valid Base64 |
| `ImageContent.mime_type` | Must be valid MIME type |
| `AgentMessage.timestamp` | Must be positive integer |

**Specification ID**: SPEC-8.1

### 8.2 Tool Arguments

**Requirement Reference**: FR-002

| Constraint | Rule |
|------------|------|
| `AgentTool.name` | Must match regex `^[a-zA-Z_][a-zA-Z0-9_]*$` |
| `AgentTool.description` | Must be non-empty string |
| `execute` function | Must return `AgentToolResult` |

**Specification ID**: SPEC-8.2

## 9. Rate Limiting

### 9.1 Message Processing

**Requirement Reference**: NFR-101

| Metric | Limit |
|--------|-------|
| Messages per session | 1000 per conversation |
| Messages per minute | 100 per session |
| Tool calls per turn | 10 concurrent |

**Specification ID**: SPEC-9.1

### 9.2 Storage Operations

**Requirement Reference**: NFR-101

| Operation | Rate Limit |
|-----------|------------|
| Read operations | 1000 per second |
| Write operations | 100 per second |

**Specification ID**: SPEC-9.2

## 10. Configuration

### 10.1 Agent Options

**Requirement Reference**: FR-001, FR-005

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `systemPrompt` | `String` | `""` | System prompt |
| `model` | `Model` | Required | LLM model config |
| `thinkingLevel` | `ThinkingLevel` | `THINKING_OFF` | Thinking mode |
| `tools` | `Vector{AgentTool}` | `[]` | Available tools |
| `messages` | `Vector{AgentMessage}` | `[]` | Initial messages |
| `steeringMode` | `QueueMode` | `QUEUE_ONE_AT_A_TIME` | Steering queue mode |
| `followUpMode` | `QueueMode` | `QUEUE_ONE_AT_A_TIME` | Follow-up queue mode |
| `toolExecution` | `ToolExecutionMode` | `EXECUTION_PARALLEL` | Tool execution mode |

**Specification ID**: SPEC-10.1

### 10.2 Session Options

**Requirement Reference**: FR-003, Solution Design SD-003

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `cwd` | `String` | Current directory | Working directory |
| `path` | `String` | Required | Session storage path |
| `metadata` | `Dict{String, Any}` | `{}` | Session metadata |

**Specification ID**: SPEC-10.2

## 11. Performance Specifications

### 11.1 Latency Targets

**Requirement Reference**: NFR-101, KPI-001

| Operation | Target Latency | 95th Percentile | 99th Percentile |
|-----------|---------------|-----------------|-----------------|
| Message processing | 200ms | 500ms | 1000ms |
| Tool execution | 500ms | 2000ms | 5000ms |
| Session recovery | 2000ms | 5000ms | 10000ms |

**Specification ID**: SPEC-11.1

### 11.2 Throughput

**Requirement Reference**: NFR-102

| Metric | Target |
|--------|--------|
| Concurrent sessions | 100 |
| Messages per session per hour | 1000 |
| Tool calls per minute | 100 |

**Specification ID**: SPEC-11.2

## 12. Traceability Summary

### 12.1 Requirement to Specification Mapping

| Requirement ID | Specification Section | Description |
|----------------|----------------------|-------------|
| FR-001 | SPEC-1.x, SPEC-2.x, SPEC-6.1 | Agent state management |
| FR-002 | SPEC-1.x, SPEC-2.x, SPEC-3.x, SPEC-6.2 | Tool execution |
| FR-003 | SPEC-4.x, SPEC-10.2 | Session persistence |
| FR-004 | SPEC-5.x, SPEC-6.1 | Event streaming |
| FR-005 | SPEC-1.x, SPEC-6.1 | Conversation management |
| FR-006 | N/A | Wine database (external) |
| NFR-101 | SPEC-11.x | Performance |
| NFR-102 | SPEC-11.x | Scalability |
| NFR-201 | SPEC-4.x, SPEC-6.1 | Availability |

**Specification ID**: SPEC-12.1

### 12.2 Solution Design to Specification Mapping

| Decision ID | Specification Section | Implementation |
|-------------|----------------------|----------------|
| SD-001 | SPEC-6.2 | AgentLoop functions |
| SD-002 | SPEC-3.x, SPEC-5.x | Tool interface, event system |
| SD-003 | SPEC-4.x | Session storage |
| SD-004 | SPEC-1.3, SPEC-3.1 | Tool execution modes |
| SD-005 | SPEC-6.1 | Queuing methods |

**Specification ID**: SPEC-12.2