Push External Events

A running Syntic Code session does not have to be a closed loop between you and Amara. External events let other systems — CI pipelines, webhooks, monitoring tools, or your own scripts — inject signals into a live session so the agent can react to things happening beyond the terminal. This turns Syntic Code into a participant in your wider automation, rather than an isolated assistant.

When to use external events

Push an event whenever something outside the session should influence what Amara does next. Common cases include notifying the agent that a build finished, that a deployment failed, that a teammate pushed a change, or that a long-running command you started elsewhere has produced output. Instead of interrupting and re-explaining context, you deliver a structured message that the agent folds into its ongoing reasoning.

Sending an event

Events are delivered to a session by its identifier. From any shell you can push a message into the named session:

# Push a build-status event into a running session
syntic events push \
  --session my-refactor \
  --type build.completed \
  --data '{"status":"failed","job":"unit-tests","log":"tests/auth_spec.js:42"}'

Amara receives the event as an inbound notification, correlates it with the current task, and can choose to act — for example, opening the failing test file and proposing a fix. Events are queued if the agent is mid-tool-call and delivered at the next safe checkpoint.

Event shape and delivery

Every event carries a type string and an arbitrary JSON data payload. Keep the type namespaced (build.completed, deploy.failed, pr.review_requested) so the agent can reason about categories of signal. Delivery is at-least-once within a session’s lifetime; if the session has already ended, the push returns a non-zero exit code so your caller can decide whether to start a fresh session instead.