[mudler-agent]

What this adds

A coordinator is an agent that keeps working on its own for a long time. It wakes on a schedule and when someone answers, starts helper agents for big tasks, writes down what it did, and contacts a named person or team only when it needs them.

The person who creates it writes its behaviour: system prompt, standing rules and topics. LocalAI decides no policy. It enforces only what the creator configured: who it may contact, how much it may send, a pause switch and an audit log.

How it works

• Creation. A coordinator is an agent plus a coordinator record (new package and tables). There is a create and edit page, an API and a card with state and usage. The agent struct is unchanged.
• One long-lived chat. Wake-ups, contact replies and helper reports all arrive as messages in that chat. Its state lives in a page folder it reads at the start of each wake-up. Writing its own page is not a proposal.
• Wake. A schedule (minimum 5 minutes), a contact's reply through a connector, or a helper finishing. A scheduled wake runs from the existing reaper leader tick, so only one frontend does it and there is no new lock key.
• Contacts. The creator lists people and teams. A person is either a LocalAI user (inbox item) or an external identity reached through a connector. A reply from a listed contact in the listed chat goes back into the coordinator's chat. Inbox contacts cannot reply there; they can talk to the coordinator in its chat.
• Guardrails, enforced by the server.
  • Send caps per minute and per day, and an audit log (90 days by default, queryable, records denied attempts).
  • A run budget and a cluster-wide cap on running coordinators, checked before a wake starts.
  • Pause: any admin can press it. It blocks all outbound, stops running turns and helpers, refuses new helpers, and holds what arrives (the owner's messages too) until resume.
  • Helper limits are settings (8 helpers, depth 2 by default; ceilings 16 and 3, set by the operator). A helper has the coordinator's rights at any depth and never gets the contact tool.
• Recovery. Helper reports are stored rows with a lease. A leader-elected sweeper delivers them, also after a restart or a dead frontend, and the coordinator is told about stopped, failed and interrupted helpers.
• Admin and assistant. An admin section lists coordinators, pauses and resumes them, and shows the audit. Four assistant tools: list, pause, resume, audit.

Decisions worth a second look

• Coordinator chats always run on the frontend, never on a chat worker, so the run budget, helper limits and contact tool always apply.
• In a cluster, chat workers and add-on owner processes no longer take the reaper lock, so the leader tick always lands on a frontend. They also no longer reap stale turns. Frontends do that.
• There is no queue for coordinator sends: a send that would queue returns "try later".
• Creation has no assistant tool: it is a user action on a feature route.

Known limits

• The answer to a contact's reply goes out through the normal messaging path, so the send caps and audit do not cover it. Only the run budget limits it.
• A user contact receives inbox messages without consent. Only the caps limit them.
• Tools the creator grants besides contact (add-on actions, commands, web tools) are not limited by the contact list or caps.
• A wake that falls due while the chat is busy is not retried until the next period.
• The concurrency limit and the helper cap are read just before a turn starts, so two coordinators starting at once can exceed them by one.
• A crash right after a report is sent, before it is marked done, can deliver that report twice.
• Loops armed by helpers are not paused by Pause. I did not check whether they can restart a helper.
• Upgrade all frontends together: an older frontend would not hold a paused coordinator or count its runs.
• No real X or social connector is part of this. No real cluster was run; leader election, leases and the two-frontend behaviour are tested with a fake bus and shared stores.
• New translations are AI-written and unreviewed.

How it was tested

• Journeys on a two-frontend fake cluster with a scripted model and a fake messaging bot: scheduled wake, contacts, helpers, reply routing, pause and resume across frontends, caps and audit, budget, a dying frontend. Each journey was made to fail by deliberately breaking the rule it covers.
• Go tests for every touched package, go test -race ./core/services/studio/..., golangci-lint with no issues, and the Postgres store suites run against a throwaway Postgres 16 (7 stores, all passing).
• UI: unit tests (1358 passed), i18n and lint gates at baseline, and Playwright over all specs except the ignored ones: 3183 passed, 49 failed. 47 failures need a missing headless browser and also fail on master. The two others are flakes that fail intermittently on master too.
• The UI coverage ratchet passes by hand (89% against a 40% baseline).
• Not run: the strict Go coverage check, the full core/http Go suite (it times out here and on master), and any real connector or provider.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DjrQyipS6MmvKffdvVGjCg