Download the PHP package koh/sylius-agent-contracts without Composer

koh/sylius-agent-contracts

Shared contracts for the koh Sylius agent-readiness bundles.

This package serves no endpoint. It exists so that the granular one-package-per-protocol split stays composable: /.well-known/api-catalog, /.well-known/agent-skills/index.json, the A2A agent card, llms.txt, auth.md and the Link: response headers all need to know what the other, independently installable bundles offer — and none of them may depend on each other to find out.

Install

Configure

What you get

AgentContext

Resolved once per request, passed through every provider. Sylius has N channels where a CMS has one site, so every discovery document is channel- and locale-dependent.

AgentContext::cacheKey() is the only sanctioned way to build a cache key in this package family. Skipping it is the classic multi-channel bug: one channel warms the cache and every other channel is served its documents.

Depend on AgentContextFactoryInterface, not the concrete class — the implementation reaches into Sylius' channel and locale contexts, which a unit test of your listener has no business booting.

The factory resolves the channel in three stages — Sylius' channel context, then a hostname lookup, then the first enabled channel. The fallback matters: ChannelContextInterface throws when no channel matches the host, which is exactly what a bot arriving over the bare IP, a preview hostname or a misconfigured proxy produces. Unhandled, that turns every /.well-known/* request into a 500 — the most common reason an agent-readiness scan fails on a multi-channel shop.

Provider interfaces

Implement one (or several) and it is picked up automatically — registerForAutoconfiguration() is registered container-wide, so this works for services in your own App\ namespace with no wiring at all.

Example — adding your own section to llms.txt:

AgentJsonResponder

One consistent response shape for every discovery document: public, max-age=3600, stale-while-revalidate=86400, an ETag (returning crawlers send If-None-Match, and a 304 is far cheaper than a rebuild), X-Content-Type-Options: nosniff and Access-Control-Allow-Origin: * — in-browser agents read these cross-origin.

AgentResponseHeaderListener

The single kernel.response listener for the whole family. Link, Content-Signal, Vary and CORS all land on the same response; with one listener per bundle they overwrite each other depending on registration order. The merge rules are enforced here:

• Link is appended, never replaced — Sylius and API Platform set their own (rel="preload", Hydra apiDocumentation) and clobbering them breaks the app.
• Vary is merged, never replaced.

Deployment note

.well-known paths fall inside Sylius' shop firewall, which is stateful (context: shop, remember_me). Without an exemption every bot hit starts a session and the responses become uncacheable. Add a dedicated entry above the Sylius firewalls — access_control is not enough, it is evaluated only after the firewall has already matched:

Decommission

Removing the package is safe once no sibling bundle is installed: drop the composer require, the entry in config/bundles.php, config/packages/koh_agent.yaml and the koh_agent_public firewall. It owns no database table, no route and no cache pool of its own.

Security

Report vulnerabilities privately — see SECURITY.md. Advisories are published as CSAF 2.0 at https://ole-hartwig.eu/.well-known/csaf/.

The family threat model, covering this package, is at https://github.com/ohartwig/sylius-agent-ready/blob/main/docs/threat-model.md.

Licence

MIT — see LICENSE.