v2.3.1

---

title: 'v2.3.1'

What's Fixed

v2.3.1 fixes a Laravel testing regression in StructuredOutput::fake().

If your application constructor-injects Cognesy\Instructor\StructuredOutput, activating the Laravel fake now keeps that dependency type-safe instead of swapping the binding to an incompatible fake object.

v2.3.0

---

title: 'v2.3.0'

What's New

v2.3.0 introduces the first substantial Symfony integration baseline for InstructorPHP.
The monorepo now includes a first-party Cognesy\Instructor\Symfony\ bundle surface with
framework-owned configuration, service wiring, delivery seams, observability, and testing support.

This release also broadens Symfony 8 compatibility in the root package, tightens the Symfony-facing
logging path, and expands the framework documentation significantly.

Symfony Integration

First-party bundle surface in the monorepo

The main package now autoloads Cognesy\Instructor\Symfony\ and includes the initial Symfony
bundle/configuration baseline directly in the monorepo. The package now owns:

• one instructor config root with explicit subtrees
• container bindings for core runtime services
• framework-native wiring for inference, embeddings, and structured output
• AgentCtrl runtime seams for HTTP, CLI, and Messenger flows
• native-agent registry, schema, tool, capability, and session wiring

This is the first release where Symfony stops looking like scattered integration glue and starts
looking like a supported framework surface.

Delivery, progress, telemetry, and sessions

packages/symfony now includes explicit delivery seams for queued AgentCtrl prompts, queued
native-agent prompts, runtime observation forwarding, CLI observation formatting, progress updates,
and package-owned telemetry/exporter lifecycle wiring.

Session persistence is also now explicit under instructor.sessions, with built-in in-memory and
file-backed paths for native agents.

Testing and migration guidance

Symfony now ships a much broader test harness and documentation set, including quickstart,
configuration, runtime surfaces, sessions, telemetry, logging, delivery, operations, testing, and
migration guides.

That gives Symfony users a clearer path for both greenfield adoption and migration from custom
bundle glue.

Logging And Observability

Symfony-facing logging ownership moved further toward the framework package in this release.

packages/symfony now includes package-owned logging factory/wiring, while packages/logging
adds correlation enrichment that merges telemetry and runtime identifiers more consistently.

The legacy standalone Symfony logging bundle path remains present, but it is now documented as a
deprecated compatibility path in favor of instructor.logging and the first-party Symfony package.

Compatibility

Symfony 8 and DocBlock 6

The root package now allows phpdocumentor/reflection-docblock:^5.6 || ^6.0.

This removes the Composer conflict that blocked Symfony 8 applications already pinned to
phpdocumentor/reflection-docblock:^6, which was the main compatibility issue reported after the
v2.2.0 release.

Documentation And QA

This release adds a large amount of framework documentation and also restores docs QA coverage that
had regressed in several packages.

That work is mostly invisible in runtime behavior, but it matters for release quality: the docs
snippets now lint cleanly again across the release-notes/docs QA sweep.

Upgrade Notes

• If you are integrating with Symfony, start from the new packages/symfony/docs/ guides and the instructor config root instead of building custom container glue around lower-level packages.
• If you depend on the legacy Symfony logging bundle wiring from packages/logging, treat it as a compatibility path. The forward-looking integration surface is the Symfony package plus instructor.logging.
• If your Symfony 8 application already requires phpdocumentor/reflection-docblock:^6, this release removes the root-package conflict and should install cleanly.
• The Symfony integration now ships in the monorepo package. Dedicated split-package publication for cognesy/instructor-symfony follows the normal split/bootstrap flow and may lag behind the monorepo release momentarily.

v2.2.0

---

title: 'v2.2.0'

What's New

v2.2.0 adds deeper telemetry across the stack. More parts of the system now share stable IDs,
correlation data, and smaller event payloads, so it is easier to trace one run from agent control,
through structured output and inference, down to HTTP.

There are also a few user-facing changes: hub can now filter examples by tag, streamed tool events
in agent-ctrl are more accurate, and agent stop handling is more predictable.

Agents And Agent Control

Telemetry from runs, tools, and subagents

agent-ctrl now assigns one executionId to each run and keeps it through the whole bridge flow.
That run can now be traced more clearly in events and in the final response.

Streamed tool events for Claude Code and Gemini were also reworked. Tool-use events now wait for the
matching tool result, so they report the real tool name, input, output, and error state instead of a
placeholder.

Cleaner stop handling in agents

AgentLoop now checks whether execution should stop before the first step and again after beforeStep.
This lets hooks stop a run cleanly without forcing another model or tool cycle.

When multiple stop signals exist, agents now picks the highest-priority reason instead of the first
one that happened to be recorded. That makes the final stop reason more consistent.

Tool calls and subagents also carry stable IDs and trace data, which makes it easier to connect parent
and child work in telemetry and logs.

Structured Output, Inference, And HTTP

End-to-end telemetry in instructor and polyglot

instructor now emits structured-output events with stable request, execution, and attempt IDs.
Streaming and non-streaming runs also report the same kind of response summary data, including finish
reason, token usage, and tool-call counts.

polyglot now carries telemetry correlation from InferenceRequest down into the underlying
HttpRequest. Stream finalization was also tightened up, so completed and failed streamed runs update
execution state more reliably.

Better request correlation in HTTP layers

http-client and http-pool now keep requestId attached more consistently, including pooled
responses and streamed HTTP events. This makes it easier to match a response or stream event back to
the request that created it, and to keep one trace chain across higher-level and lower-level layers.

Failure events in instructor and polyglot were also cleaned up so they report smaller, safer
summaries instead of large raw payloads.

Hub

hub list now supports --tag and --tags, and examples can carry normalized tag metadata. This
makes it easier to find examples by topic without scanning the whole catalog.

Upgrade Notes

• If you read raw event payloads from agent-ctrl, agents, instructor, polyglot, http-client, or http-pool, review them before upgrading. Several events now include new IDs, summary fields, and different payload shapes.
• In agents, the final stop reason may differ from earlier releases because stop signals are now resolved by priority.
• In agent-ctrl, some streamed tool events are emitted later than before, but they now contain the actual tool result data.

v2.1.0

---

title: '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:

$stateFactory = new DefinitionStateFactory();
$sessionFactory = new SessionFactory($stateFactory);
$session = $repo->create($sessionFactory->create($definition));

After:

$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():

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().

v2.0.0

---

title: 'v2.0.0'

What's New

v2.0 is a ground-up rework focused on performance, type safety, and a tighter API surface.

• Faster, leaner — streaming is more memory efficient, execution is lazy by default,
  and internal code paths have been consolidated.
• Tighter APIs — both Instructor and Polyglot have cleaner, more type-safe public APIs
  with explicit fields instead of mode-based configuration.
• More reliable — extensive unit, feature, integration tests and benchmarks back this
  release. A substantial number of bugs have been fixed across the stack.
• Agent building blocks — new cognesy/agents package for custom agents, and an expanded
  cognesy/agent-ctrl to interact with CLI coding agents from PHP.

Breaking Changes

• Instructor's public API centers on StructuredOutput, StructuredOutputRuntime,
  PendingStructuredOutput, StructuredOutputResponse, and StructuredOutputStream.
• Polyglot uses explicit LLM API fields (responseFormat, tools, toolChoice) instead
  of output modes. Streaming moves to stream()->deltas().

Instructor

• Execution flows through StructuredOutputRuntime, with lazy execution via PendingStructuredOutput.
• Streaming is Instructor-owned: StructuredOutputStream exposes responses(), partials(),
  and sequence(). StructuredOutputStreamState accumulates state internally.
• Configuration, validation, transformation, deserialization, and extraction are explicit
  parts of the runtime rather than scattered across older code paths.

Polyglot

• InferenceRuntime and EmbeddingsRuntime sit behind the Inference and Embeddings facades.
• New inference drivers: openai-responses, openresponses, glm, qwen.
• Built-in pricing via Pricing\Cost, per-model pricing objects, and cost calculators.
• Polyglot handles raw transport — structured value ownership belongs to Instructor.

Agents (cognesy/agents)

New package. Building blocks for custom agents: AgentLoop, AgentBuilder, hooks, guards,
templates, subagents, skills, and SessionRuntime for persisted workflows.

Compose agents from capabilities like bash, file tools, structured outputs, summarization,
self-critique, planning, execution history, and broadcasting.

Two built-in drivers: ToolCallingDriver (native tool-calling APIs) and ReActDriver
(Thought/Action/Observation loops).

AgentCtrl (cognesy/agent-ctrl)

Unified PHP API for interacting with CLI coding agents — Claude Code, Codex, OpenCode,
Pi (new), and Gemini (new).

• AgentCtrl::make() and dedicated builders (::codex(), ::openCode(), ::pi(),
  ::gemini()) return normalized AgentResponse objects.
• Streaming callbacks, session resume/continue, typed IDs (AgentSessionId,
  AgentToolCallId), and AgentCtrlConsoleLogger for observability.

Migrating from v1.x

• Instructor: use ->get(), ->response(), and ->stream(). For partial snapshots,
  switch to stream()->responses(), stream()->partials(), or stream()->sequence().
• Polyglot: replace mode-based JSON/tool config with responseFormat, tools,
  toolChoice, and delta-based streaming.
• See packages/instructor/docs/upgrade.md and packages/polyglot/docs/upgrade.md for details.