[francisrath]

Draft, not ready to merge. This hasn't been tested enough yet: one developer, one Brother QL, the Docker dev setup with SQLite (the migration was also run up and down on MySQL 8 and PostgreSQL 14). I'm opening it to get your feedback on the approach before polishing it.

Part of #1625; the second of three alternative PRs. It includes #1626. The commits new here start at "feat(agents): agent and agent job entities".

With #1626 the browser has to run on the same computer as the agent. This PR lets Part-DB keep the jobs instead: the agent connects outbound to Part-DB and fetches them. Printing then works from any device, phones included, and through NAT, with the agent on a PC or a Raspberry Pi next to the printer.

What it adds

• Entities Agent and AgentJob, plus a migration for MySQL, PostgreSQL and SQLite.
  • An agent belongs to the user whose API token registered it.
  • A job is {type: "print", printer, payload: {profile_id, element_type, element_ids}} with a status.
  • There is no printer-specific schema: printers are whatever the agent reports.
• A small JSON API under /<locale>/agent-api/v1, documented in docs/usage/labels.md:
  • POST agents/<uuid>/heartbeat: the agent registers and reports its printers.
  • GET agents/<uuid>/jobs
  • POST jobs/<id>/claim: atomic; returns 409 if the job was taken.
  • POST jobs/<id>/result
  • Only API tokens are accepted, and a read-only token is enough. The user needs the existing "create labels" and "access API" permissions; there are no new permissions. Users only see their own agents and jobs.
• Print buttons send jobs to the agent:
  • The label generator gets a "Print on " split button.
  • The label menus get a one-click printer icon for profiles with a default printer.
  • The parts tables get "Print labels" bulk actions.
  • The Print button that hands labels to a local print agent #1626 local handoff stays available as "This computer".
• A default printer per label profile, a free-text printer id with suggestions from the user's agents.
• The agents page (Tools → Print agent) lists agents, their printers and recent jobs, with send again, cancel and remove.

Part-DB never re-queues a job by itself. A job claimed but never reported shows as "unknown" after 10 minutes, and the user can send it again. Finished jobs are deleted after 30 days.

Screenshots

The Print button in the label dialog, with the printer picker:

The menu icon that sends a label straight to the profile's default printer:

The agents page (Tools → Print agent):

Decisions you may want differently

• A plain JSON controller, not API Platform resources. The API is small and agent-specific; it moves easily if you prefer API Platform.
• The API sits under the locale prefix, like the KiCad API.
• No settings toggle. Nothing changes until a user registers an agent.

Tests

• New tests: AgentApiControllerTest, LabelControllerTest (many new cases), PartsTableActionHandlerTest, tests/Entity/AgentSystem/AgentJobTest.php.
• PHPStan (level 5), lint:twig and doctrine:schema:validate pass.
• Tested by hand against the Docker dev setup with pdb-print: the menu icon, the dialog, the agent offline and then back, and "Send again".
• The parts-table bulk action was not clicked through in a browser.

🤖 Generated with Claude Code