0.9.0

Neuron Interaction 0.9.0 supports Neuron AI 4 and separates saved conversations from the Agent's active model context.

Requirements

Requires PHP 8.4.1+ and neuron-core/neuron-ai:^4.0. Applications using Neuron AI 3 should remain on asterixcapri/neuron-interaction:^0.8.

composer require asterixcapri/neuron-interaction

Breaking changes: sessions and Agent binding

Session no longer extends Neuron's chat history. SessionMessageStore implements Neuron AI 4's MessageStoreInterface and persists active and archived messages. Bind a Session explicitly and retain the returned Agent copy:

// Before
$session = $sessionStore->create();
$agent->setChatHistory($session);

// After
$session = $sessionStore->create();
$agent = $session->bindTo($agent);

• Replace Session::title() with Session::getTitle().
• Session::getMessages() reloads the complete saved conversation, including archived messages. Use a fresh $agent->getChatHistory() to read the active model context after a turn.
• Configure context-window behavior on the Agent. The Session constructor no longer accepts contextWindow, trimmer or document arguments.
• Replace inherited Session history operations with operations on the bound Agent's chat history or the Session's message store. Clearing the history deletes both active and archived messages.
• Listings include conversations whose user messages have been archived. Empty conversations remain excluded.

Existing Neuron AI 3 Session documents remain readable; no manual migration is required for those documents. New writes use Neuron AI 4 serialization, preserving message IDs, content blocks, metadata and structured tool outputs. Applications reading raw serialized messages must account for Neuron 4's __meta metadata field and changed tool serialization. UserMessageFactory now uses Neuron's MessageDeserializer and no longer extends InMemoryChatHistory.

Breaking changes: command Adapters

Custom CommandAdapterInterface implementations must add:

public function session(): Session;
public function useSession(Session $session): void;

Keep the current Session alongside the Agent. useAgent() binds the replacement Agent to that Session; useSession() validates ownership through the Adapter's SessionStore and binds the current Agent to the selected Session. Retain the Agent copy returned by bindTo() in both cases.

/clear and /resume now call useSession(). Read adapter->agent() after a Command to obtain the current instance. The example BackendAdapter creates an empty Session by default; pass an explicit Session with its matching Store to continue an existing conversation across requests. An Agent with existing messages requires an explicit Session.

Breaking changes: stopping responses

StopSignal moves from NeuronInteraction\Http to NeuronInteraction\Interruption. The package's StoppableHttpClient and StoppableStream are removed in favor of Neuron AI's native implementations.

use NeuronAI\HttpClient\StoppableHttpClient;
use NeuronInteraction\Interruption\StopSignal;

$stopSignal = new StopSignal(storage: $storage, key: $chatId);
$client = new StoppableHttpClient(
    client: $httpClient,
    shouldStop: $stopSignal->stopCallback(),
);

Pass client: instead of inner:, and shouldStop: instead of stopSignal:. Move onPoll: and pollInterval: into stopCallback(); the polling interval defaults to 0.01 seconds. Share the signal's Storage and key with the stop action, clear it before each response, and call request() to stop. The callback consumes the flag.

Neuron finalizes partial text with the stopped finish reason. Stopping before any text raises ProviderException. Incomplete tool calls are discarded; local tools and later inference are not cancelled. Remote generation cancellation is not guaranteed.

Neuron AI 4 execution changes

chat() executes immediately and returns AgentState. stream() returns a lazy generator: iterate it directly instead of calling events(), then retrieve the final message after consuming it:

$stream = $agent->stream(new UserMessage($prompt));
foreach ($stream as $event) {
    // Handle chunks.
}
$response = $stream->getReturn()->getMessage();

Session binding supplies the Agent's thread ID. Agents used outside a Session must be assigned a thread ID before execution. See the Neuron AI 4 migration guides for other dependency API changes affecting custom Agents, providers and tools.

Full changelog: 0.8.8...0.9.0