Ten bots, one mandate

1Mandate

Bots prepare, people decide. The bots watch orders, stock and the calendar; they draft, check, remind and flag. They never move stock, commit money, or promise anything to a customer on their own. Every bot action shows on the dashboard as one plain-English line, and every bot has a kill switch.

2The ten bots

3Autonomy levels

Raising an action from L2 to L3 needs an admin setting change and a written confirmation by the business owner. There is no automatic "autonomy creep".

4Eight rules that make the loop real

1. Named human, not "the system" — every approval records decided_by and time.
2. Reversible by default — bots only create proposals, flags and messages; undo is always one click.
3. Escalate, don't guess — low-confidence extraction or ambiguity goes to the human queue; the bot never retries into a wrong answer.
4. Kill switch per bot and per action type — in Admin → Agents.
5. No silent autonomy creep — level changes are logged and need two people.
6. Stock, money and customer promises stay L1.
7. Human override wins — if a person rejects a bot proposal, the reason is captured and the bot does not re-propose the same thing.
8. Loop health is monitored — proposals waiting too long show on the digest like overdue orders.

5Daily schedule

6Decision rights

7Technical design

7.1 Runtime

• Hosting cron is confirmed available (4 Oct 2026).
• Bots 1–8 and 10 are PHP CLI jobs in includes/agents/, started by the host's cron: php stock_control.php --agent=<name> (blocked from web access).
• One cron entry every 5 minutes runs --agent=dispatcher, which decides which bots are due (from agent_schedule), so only one cron line is needed.
• Each run takes a lock (agent_runs row) so two runs never overlap.

7.2 Event stream

• Every order / stock change writes to events (type, entity, entity_id, payload, created_at). Bots read events since their last cursor.
• Examples: order.created, order.invoiced, order.confirmed, line.short, stock.in, allocation.created, order.dispatched, xlsm.synced.

7.3 New tables (additive)

CREATE TABLE IF NOT EXISTS events (
  id INTEGER PRIMARY KEY AUTOINCREMENT, type TEXT NOT NULL,
  entity TEXT NOT NULL, entity_id INTEGER, payload TEXT DEFAULT '{}',
  username TEXT DEFAULT '', created_at TEXT DEFAULT (datetime('now','localtime'))
);
CREATE TABLE IF NOT EXISTS agent_settings (
  agent TEXT PRIMARY KEY, enabled INTEGER DEFAULT 0,
  level TEXT DEFAULT 'L2', config TEXT DEFAULT '{}',
  updated_by TEXT DEFAULT '', updated_at TEXT DEFAULT ''
);
CREATE TABLE IF NOT EXISTS agent_proposals (     -- the human approval queue
  id INTEGER PRIMARY KEY AUTOINCREMENT, agent TEXT NOT NULL,
  kind TEXT NOT NULL,                            -- draft_order | allocation | email | booking | make_list
  entity TEXT, entity_id INTEGER, summary TEXT NOT NULL,
  payload TEXT NOT NULL, confidence REAL DEFAULT 1.0,
  status TEXT DEFAULT 'PENDING',                 -- PENDING | APPROVED | REJECTED | EXPIRED
  decided_by TEXT DEFAULT '', decided_at TEXT DEFAULT '', reason TEXT DEFAULT '',
  created_at TEXT DEFAULT (datetime('now','localtime'))
);
CREATE TABLE IF NOT EXISTS agent_runs (
  id INTEGER PRIMARY KEY AUTOINCREMENT, agent TEXT NOT NULL,
  started_at TEXT, finished_at TEXT, status TEXT, cursor_event_id INTEGER DEFAULT 0,
  summary TEXT DEFAULT '', error TEXT DEFAULT ''
);
CREATE TABLE IF NOT EXISTS agent_log (            -- one plain-English line per action
  id INTEGER PRIMARY KEY AUTOINCREMENT, agent TEXT NOT NULL,
  message TEXT NOT NULL, level TEXT DEFAULT 'info',
  entity TEXT, entity_id INTEGER, created_at TEXT DEFAULT (datetime('now','localtime'))
);

7.4 AI usage

• Only the Order Intake Bot needs a language model (reading free-form emails / PDFs). Server-side call to the Claude API; key stored in a config file outside public_html, never in source or the browser.
• Prompt returns strict JSON (customer, PO, dates, lines[code, description, qty, unit]); every field carries a confidence. Unknown product codes are matched against products by name; anything < 0.85 confidence is highlighted for the human.
• All other bots are plain rules over the database — predictable, cheap, testable.
• Data sent to the model: the order email/attachment text only. No user passwords, no ledger.

7.5 Screens

• Bot inbox (?page=agents) — pending proposals with Approve / Edit & approve / Reject (reason). Badge count in the header.
• Activity feed on the home page — latest agent_log lines.
• Admin → Agents — per-bot on/off, level, schedule, last run, error, acceptance rate.

7.6 Hermes (bot 9)

• Runs on a small VPS or always-on office PC (the messaging gateway is a persistent process the shared host can't run).
• Talks to the app only through ?api=agent_unseen, ?api=agent_reminder, ?api=agent_ack with a bearer token. Details in DASHBOARD.md §4.

7.7 Hosting checks still needed

• ✅ Cron available.
• PHP imap extension (or a mailbox that can forward to a pipe / webhook) for the Order Intake Bot.
• Outbound HTTPS allowed (Claude API, later Xero API).
• pdftotext or a PHP PDF text library for PDF POs.