> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instructorphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# V2.1.0

## What's New

### SessionRuntime::create() — single entry point for session creation

`SessionRuntime` now exposes a `create(AgentDefinition $definition, ?AgentState $seed = null)` method
that handles the full session creation lifecycle: instantiation, hook processing, persistence, and
event emission — all in one call.

**Before:**

```php theme={null}
$stateFactory = new DefinitionStateFactory();
$sessionFactory = new SessionFactory($stateFactory);
$session = $repo->create($sessionFactory->create($definition));
```

**After:**

```php theme={null}
$session = $runtime->create($definition);
```

The new method runs through the same hook and event pipeline as `execute()`, so session controllers
fire consistently for both creation and updates.

### Dedicated BeforeCreate / AfterCreate hook stages

The `AgentSessionStage` enum gains two new cases: `BeforeCreate` and `AfterCreate`.

During `SessionRuntime::create()`, hooks fire in this order:

1. `BeforeCreate` — create-only pre-persist logic (e.g. set defaults, assign IDs)
2. `BeforeSave` — shared pre-persist logic (fires on both create and execute)
3. **persist**
4. `AfterSave` — shared post-persist logic (fires on both create and execute)
5. `AfterCreate` — create-only post-persist logic (e.g. send notifications)

The `execute()` pipeline is unchanged — it continues to fire only `BeforeSave` / `AfterSave`.
This layered approach (inspired by Eloquent's `creating`/`saving`/`saved`/`created` events)
lets hooks distinguish between first-time creation and subsequent updates.

### SessionFactory is now injectable

`SessionRuntime` accepts an optional `?SessionFactory` constructor parameter. It defaults to
`new SessionFactory(new DefinitionStateFactory())` when omitted, so existing call sites are
unaffected — but custom state factories can now be injected for testing or advanced use cases.

### CanManageAgentSessions contract updated

The `CanManageAgentSessions` interface now includes `create()`:

```php theme={null}
interface CanManageAgentSessions
{
    public function create(AgentDefinition $definition, ?AgentState $seed = null): AgentSession;
    public function listSessions(): SessionInfoList;
    public function getSessionInfo(SessionId $sessionId): AgentSessionInfo;
    public function getSession(SessionId $sessionId): AgentSession;
    public function execute(SessionId $sessionId, CanExecuteSessionAction $action): AgentSession;
}
```

### When to use SessionFactory + repo directly

`SessionFactory` and `SessionRepository::create()` remain available for the one case where
you already have a fully constructed `AgentSession` — forking. `ForkSession` returns a
concrete session instance, so you persist that branch via `$repo->create($forked)` rather
than going through `SessionRuntime::create()`.