Events
PSR-14 events this extension dispatches, and what you may rely on about them.
Each is @api: within a major version it is not removed, its properties do
not disappear and their types do not change. Listeners are registered the
ordinary TYPO3 way, in your own extension's Configuration/Services.yaml.
AfterAiRecordWrittenEvent
Netresearch
Dispatched once per successful editorial write, after the write has landed and been read back by the tool that made it. For a run with an assignment scope it is dispatched before the call's transaction is committed, under that scope (see below). It answers three questions and no fourth.
-
- type
-
string
The agent run's uuid, which is the correlation id of everything that run did. It is what
tx_holds, so a listener that needs the run — its actor, its configuration, its trace — resolves it by this value. Never empty.nrllm_ agentrun. uuid
-
- type
-
NetresearchNr Llm Domain Value Object Record Reference
The row the write produced or changed: a table name and a uid, and
__renders them asto String () pages:.42
-
- type
-
NetresearchNr Llm Domain Enum Write Kind
Writewhen a record is created,Kind:: CREATED Writewhen it is changed,Kind:: UPDATED Writewhen the call wrote no AI text: it was moved, published or copied, only settings changed, or a draft still holds the source text, andKind:: TEXT_ UNCHANGED Writewhen the delete tool soft-deletes it. A deletion still names the target row; the event carries no copy of its former values.Kind:: DELETED
A listener
use Netresearch\NrLlm\Domain\Enum\WriteKind;
use Netresearch\NrLlm\Event\AfterAiRecordWrittenEvent;
final readonly class LabelAiWrittenPages
{
public function __construct(
// Your own service: nr_llm records the fact (ADR-239), and what
// a site says about an AI-written record is the site's decision.
private AiTransparencyLabelRepository $labels,
) {}
public function __invoke(AfterAiRecordWrittenEvent $event): void
{
if ($event->record->table !== 'pages') {
return;
}
if (!in_array($event->kind, [WriteKind::CREATED, WriteKind::UPDATED], true)) {
return;
}
$this->labels->record(
$event->record->uid,
$event->kind === WriteKind::CREATED ? 'ai-generated' : 'ai-assisted',
$event->correlationId,
);
}
}
services:
Vendor\Extension\EventListener\LabelAiWrittenPages:
tags:
- name: event.listener
identifier: 'vendor/label-ai-written-pages'
What it deliberately does not carry
No record payload. Not the field values, not a before/after, not a rendered excerpt, not the tool's name. A payload is a copy, and a copy of editorial content is a second place for it to leak from and a second place for it to go stale. record names the row; read it yourself, under your own permissions, at the moment you need it.
One listener of ours, which only records the fact.
Mark sets tx_ on pages and
tt_ (ADR-239). An Article 50 transparency label, a
badge in the page module, a line in an existing editorial audit trail and a
nightly compliance report are four different artefacts with four different
owners; which of them your site wants is your decision
(ADR-187).
No actor. Which backend user the run acted for is persisted on the run; resolve it by correlationId rather than expecting a second copy of an identity on every event.
Two properties worth knowing before you write a listener
It fires before the run trace persists its step for the same call. Do not try to join the run's trace for this write — it is not there yet. Everything the event promises is on the event.
A listener that throws is logged, not propagated. The write has already
landed and a human has already approved it, so a broken listener does not fail
the run — it produces an error-level log entry naming the record. Do not
rely on an exception to signal anything back to the extension. In a run with
an assignment scope, a DataHandler write of the listener outside the scope
does fail the call (see below).
It can fire twice for one record. The agent queue is at-least-once: a run whose lease is lost may be re-executed, and an idempotent write that runs twice dispatches twice with the same correlationId and record. Deduplicate on that pair if your listener must act once per record. A non-idempotent write is never auto-retried, so it cannot double this way.
A listener of a run with an assignment scope
A run can be bound to the scope of its assignment
(ADR-295). Its write events, this one and the internal
Ai, are then dispatched while the scope holds the call and
before its transaction is committed: the write the event names can still be
rolled back after your listener ran, by another listener's write outside the
scope or by a failed commit. Keep effects outside the database (a mail, a
webhook, a queue message) out of such a listener, or make them tolerate a
write that did not stay. A DataHandler write of a listener is held
to the scope like the call's own write: a write outside the scope rolls back
the whole call, the call's own write included, and the model is told which
record and which rule. A write of the record the call wrote, or of its draft,
is inside the scope. When TYPO3 adds an entry for a translation in a language
the scope does not admit to such a write, the entry is left out without a
refusal, as for the call's own write, and the translation gets no version,
when the write synchronises nothing: the added entry holds only synchronised
fields and l10n_, no submitted entry names a synchronised field, and
no inline or file field in it lists a child record. Any other such entry is
judged as before; the scope refuses it and the call fails. On MySQL and
MariaDB a TCEMAIN. group flush in a listener's run commits
the call early, and a later violation can no longer roll it back
(ADR-295).
A listener that has to write outside the scope, a log record on a storage page for example, wraps exactly that write and gives the reason:
use Netresearch\NrLlm\Service\Tool\Scope\WriteOutsideTheAssignmentScope;
WriteOutsideTheAssignmentScope::run(
'editorial audit log of AI writes',
fn () => $this->auditLog->record($event),
);
The write is not judged, is listed with the call's changes, and is logged as a warning with the reason; a rollback of the call takes it back with the rest. This works only while such an event is dispatched: called anywhere else, during a tool's own execution too, the write is held to the scope as before. Nothing in nr_llm calls it, so without an integrator's code no listener write leaves the scope.