Automation & the local agent

The protocol of the local executing agent and the automation worker.

Decoupled background execution service (orazaka-automation-service) and the NAT-bypassing Local Agent Protocol.

1. Architectural Setup

Architecture · orazaka-automation-service

Automation service — connector execution, CLI-agent dispatch and scheduling (own database)

Hexagonal Isolation: The worker is fully isolated. It has zero dependency on orazaka-conversation-service.
Communication Invariant: Inter-module sync is handled via the RabbitMQ broker.
Zero Inbound Ports: The worker runs in a secure cluster mesh; the local CLI agent connects outbound to the gateway to fetch requests.

Automation scheduling states are persisted in the PostgreSQL database:

Quartz config: spring.quartz.job-store-type = jdbc with postgres driver delegate.
Flyway Integration: Flyway migrations are disabled on the worker.

The worker does not integrate with actual cloud APIs or Apache Camel routing. Instead:

Connector Dispatcher: Outbound actions (Jira, Slack, Messenger, WhatsApp) are implemented as log-stubs in ConnectorDispatcher.java (orazaka-apps/workers/external-services/).
Execution Logs: Dispatching acts as a stub simulation logging payload metadata.
CLI Agent Routing: If the type is CLI_AGENT, it correctly serializes and dispatches to RabbitMQ under the cli.{userId}.dispatch routing key for remote CLI execution.

Sequence — text version

Participants

Phase 1 — secure reverse registration
Step 1orazaka-cli → orazaka-conversation-service: GET /api/v1/agent/stream (Bearer token)
Step 2orazaka-conversation-service → orazaka-conversation-service: validate the session JWT (krizaka-security)
Step 3orazaka-conversation-service → RabbitMQ · orazaka.jobs / orazaka.events: publish evt.agent.presence
Step 4orazaka-conversation-service replies to orazaka-cli: SSE tunnel established
Phase 2 — job dispatch
Step 5orazaka-automation-service → RabbitMQ · orazaka.jobs / orazaka.events: publish job.agent.dispatch.{userId}
Step 6RabbitMQ · orazaka.jobs / orazaka.events replies to orazaka-conversation-service: deliver the job of this user
Step 7orazaka-conversation-service replies to orazaka-cli: SSE event automation_payload
Phase 3 — local consent and execution
Step 8orazaka-cli → orazaka-cli: ask the user: Execute this action? [Y/n]
Step 9orazaka-cli → orazaka-cli: run the approved script locally
Step 10orazaka-cli → orazaka-conversation-service: POST /api/v1/agent/report (result JSON)
Step 11orazaka-conversation-service → RabbitMQ · orazaka.jobs / orazaka.events: publish evt.agent.result.{jobId}

Phase 1 (Registration): The CLI opens an SSE channel (GET /api/v1/agent/stream). Gateway registers the channel and broadcasts metadata.
Phase 2 (Dispatch): The automation worker posts a job payload (containing script and directory limits) to RabbitMQ. The Gateway consumes and proxies it via the SSE stream.
Phase 3 (Consent & Execution): The CLI agent prompts the user in the terminal (Execute this action? [Y/n]). If approved, the command runs and output is reported via POST /api/v1/agent/report.

NAT Bypassing: SSE pulls commands outbound; no firewall inbound rules needed.
User Verification: Interactive prompt confirmation [Y/n] blocks unapproved command runs.
Sandboxing: Script actions restricted to user-configured directory lists.
Transport: Secured with TLS. Timeout limits (default 300s) evict hung scripts.

Exchange	Type	Routing Key	Queue	Consumer
`orazaka.automation.exchange`	Topic	`job.approved`	`orazaka.automation.jobs`	Worker (`AutomationJobListener`)
`orazaka.automation.exchange`	Topic	`cli.{userId}.dispatch`	Per-User Dispatch	Gateway
`orazaka.automation.exchange`	Topic	`cli.{userId}.result`	Per-User Result	Worker (`AutomationJobListener`)
`orazaka.cli.exchange`	Fanout	`cli.online`	`orazaka.cli.heartbeat`	Gateway
`orazaka.identity.events`	Topic	`user.registered`	`orazaka.workers.identity.registration`	Worker (`IdentityNotificationListener`)
`orazaka.identity.events`	Topic	`password.reset`	`orazaka.workers.identity.password`	Worker (`PasswordNotificationListener`)