Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Notable changes in each release, newest first. Releases before 0.9.7 are describ

## Unreleased

- Pause everything (Beacon iOS): `PUT /api/pause` stops the whole agent and keeps it stopped. It writes the state to disk first, withdraws every pending approval, stops desktop tasks, tasks and workers, and pauses every coding run through its control file, so the work is kept. Turns started through the WebSocket, the REST chat routes and `/v1` are cancelled at once. Every other turn (Telegram, Slack, Discord, the scheduler) stops at its next round, so a tool call already running finishes first, until a follow-up gives those turns tasks of their own; nothing new that needs an approval can start, since every pending approval is withdrawn. While paused, no new turn starts: the chat and OpenAI-compatible routes answer `423 paused`, and the agent loop itself refuses to start. A restart comes back paused, and an unreadable pause file counts as paused. `DELETE /api/pause` resumes, and only for a person: a device carrying the new person mark, which the owner sets in their own Telegram with `/person allow <device id>` (`/person disallow` removes it, `/person` lists). The mark does nothing but allow resume: it is not the computer-use mark, and no REST route sets it. The owner can also pause and resume from their own Telegram with `/pause [reason]` and `/resume`, which nobody else can use, so a pause can always be lifted, even with no device marked. The API token cannot resume, and neither can a device without the mark, an owner device included, since the token can mint one. Resuming starts nothing. A pause holds even when its file cannot be written, and the answer then says `persisted: false`. The pause file is in the trusted-state floor (the gate, Seatbelt and the AppArmor profile), so the agent's shell cannot write or remove it; on Linux, reload the installed AppArmor profile to get the rule. `/api/status` gains `paused`, `GET /api/pause` answers `{paused, since}` to any device (a chat-only phone included, never who or why), `server_capabilities` lists `pause`, and a coding run's control file is now written atomically. The push alert and a doctor row follow. Every worker and coding run the daemon starts, and every model-written shell it starts as a task, a watcher or a cron job, is told the exact pause file (`PROMETHEUS_PAUSE_FILE`) and passes it on; one that cannot reach its folder treats the agent as paused. A turn from Telegram, Slack or Discord now runs as a task of its own, so a pause cancels it at once, like a turn from the web, instead of letting it finish its round. While paused, a cron job that falls due is skipped and recorded as `skipped` (its next run moves on, nothing is saved up), side model calls (titles, conversation summaries, memory extraction, the curator's model review) are not made and do not count as failures, a prompt hook that cannot be asked blocks its event, `POST /api/code`, `POST /api/computer/tasks` and `POST /api/cron/{name}/run` answer `423`, and Telegram's `/computer yes` starts no desktop task.
- Pause everything (Beacon iOS): `PUT /api/pause` stops the whole agent and keeps it stopped. It writes the state to disk first, withdraws every pending approval, stops desktop tasks, tasks and workers, and pauses every coding run through its control file, so the work is kept. Turns started through the WebSocket, the REST chat routes and `/v1` are cancelled at once. Every other turn (Telegram, Slack, Discord, the scheduler) stops at its next round, so a tool call already running finishes first, until a follow-up gives those turns tasks of their own; nothing new that needs an approval can start, since every pending approval is withdrawn. While paused, no new turn starts: the chat and OpenAI-compatible routes answer `423 paused`, and the agent loop itself refuses to start. A restart comes back paused, and an unreadable pause file counts as paused. `DELETE /api/pause` resumes, and only for a person: a device carrying the new person mark, which the owner sets in their own Telegram with `/person allow <device id>` (`/person disallow` removes it, `/person` lists). The mark does nothing but allow resume: it is not the computer-use mark, and no REST route sets it. The owner can also pause and resume from their own Telegram with `/pause [reason]` and `/resume`, which nobody else can use, so a pause can always be lifted, even with no device marked. The API token cannot resume, and neither can a device without the mark, an owner device included, since the token can mint one. Resuming starts nothing. A pause holds even when its file cannot be written, and the answer then says `persisted: false`. The pause file is in the trusted-state floor (the gate, Seatbelt and the AppArmor profile), so the agent's shell cannot write or remove it; on Linux, reload the installed AppArmor profile to get the rule. `/api/status` gains `paused`, `GET /api/pause` answers `{paused, since}` to any device (a chat-only phone included, never who or why), `server_capabilities` lists `pause`, and a coding run's control file is now written atomically. A new pause pushes one "Prometheus paused" alert, saying who paused (never why), to owner devices with no live connection; `oara doctor` has a Pause row (an unreadable pause file is an error that counts as paused); the curator archives nothing while paused (`/curator run` refuses); and a pause file with a nonsense time counts as paused instead of stopping the daemon from starting. Every worker and coding run the daemon starts, and every model-written shell it starts as a task, a watcher or a cron job, is told the exact pause file (`PROMETHEUS_PAUSE_FILE`) and passes it on; one that cannot reach its folder treats the agent as paused. A turn from Telegram, Slack or Discord now runs as a task of its own, so a pause cancels it at once, like a turn from the web, instead of letting it finish its round. While paused, a cron job that falls due is skipped and recorded as `skipped` (its next run moves on, nothing is saved up), side model calls (titles, conversation summaries, memory extraction, the curator's model review) are not made and do not count as failures, a prompt hook that cannot be asked blocks its event, `POST /api/code`, `POST /api/computer/tasks` and `POST /api/cron/{name}/run` answer `423`, and Telegram's `/computer yes` starts no desktop task.
- Docs: `docs/reference/pairing-join-requests.md` is the reference for how a new device asks to join and how the owner lets it in: the routes and who may call them, every request and response field, the statuses, the expiry and rate limits, the sealed token, the operator's WebSocket frames and the owner code (the explicit, single-use grant that makes an owner device). It is written from the code and pinned to it by `tests/test_pairing_reference.py`. No behaviour changes.
- Approvals: Prometheus now says when nothing can answer an approval prompt. `security.approval_queue.enabled` ships `false`, and the queue is only built together with the Telegram gateway; without it every call that needs an approval (a third-party MCP tool, a write or a shell command in `cautious` or `strict` mode, a network or install command in a background turn) is refused within seconds as "Permission denied" and none is ever listed to approve, so `cautious` read as "asks the owner" and behaved as "refuses everything". The daemon logs a warning at start and `oara doctor` has an "Approval prompts" row, both naming the keys to set. Nothing is switched on for you.
- Approvals: the grants in `security.grants` are now loaded when the daemon starts. A remembered approval (`/approve always`) was written to the file and then ignored at every restart, so the prompt it silenced came back each time, and a `kind: tool` row written by hand (for one third-party MCP tool) never took effect. After this, a grant lasts until you `/revoke` it. **On upgrade, grants saved by earlier versions take effect again at the first start:** the startup log lists each one by id, kind and tool, `/grants` shows them in full, and `/revoke` removes one. The daemon and `SecurityGate.from_config` now read the key in one place.
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ app and kept current by CI, see
| POST | `/api/identity/challenge` | Unauthenticated, so a paired client can check which Prometheus it reached **before** it sends its token. Body `{"v": 1, "nonce": <base64url of exactly 32 random bytes>}`; answer `{v, instance_id, node_pub, tls_spki_sha256, signed_at, sig}`, where `sig` is the node key's Ed25519 signature over six lines, each ending in a newline: `prometheus-identity-challenge/v1`, `nonce=<as sent>`, `instance_id=<uuid or empty>`, `node_pub=<base64>`, `tls_spki_sha256=<hex or empty>`, `signed_at=<seconds>`. `tls_spki_sha256` is the served certificate's SPKI digest on the TLS port and `null` on the plain one. Over TLS the signature binds the node key to the channel; over a plain listener it proves the real instance is reachable, not that nothing sits in between. `400 bad_nonce`, `503 no_node_key` before first run (the route never makes the key), and hello's limits: no `Origin`, 60 a minute per peer shared with hello, never cached, no cookie. Stateless. |
| POST | `/api/restart` | Operator only. Answers `202 {"restarting": true}`, then the daemon shuts down gracefully and starts again in the same process (it re-execs its own command line), so a saved setting such as the network mode takes effect without anyone touching the machine. Every socket drops; wait for `GET /api/hello` to answer with the same `fp`. `503 restart_unavailable` from a process that was not started as the daemon. The restart runs with the environment the daemon first started with, so the env file is read again (a rotated token takes effect). Refused to a web page: an `Origin` header is `400 browser_not_allowed`. |
| GET | `/api/status` | Model, uptime, tools, memory, subsystem states — plus `node_pub` (the node's Ed25519 public key) and `instance_id` (the vault's UUID), both `null` until identity exists, and `name` and `fp`, the same values `GET /api/hello` answers (`fp` is `""` until the instance key exists). Bearer-gated deliberately; `/health` never carries identity. `paused`: `null`, or `{since, by, reason}` while everything is paused (`PUT /api/pause`) |
| PUT | `/api/pause` | Pause everything. Operator (the API token or an owner device); a scoped device gets `403 operator_only`. Body `{reason?}`. Writes the state to disk first, withdraws every pending approval, cancels every turn running in the daemon (the WebSocket, the REST chat routes, `/v1`, Telegram, Slack and Discord), stops desktop tasks, tasks and workers, and pauses (keeps) every coding run. A worker or coding run, a process of its own, also stops at its next round, and one that cannot reach the pause file's folder counts as paused. Answers `{paused: true, since, by, reason, persisted, stopped: {turns, desktop_tasks, tasks, coding_runs, approvals_withdrawn}}` and broadcasts `paused_changed` `{paused, since}` (who and why are on `/api/status`). The pause holds even if the file cannot be written; `persisted: false` then says it will not survive a restart. Idempotent: a second call is the same pause (same `since`). While paused, `POST /api/chat/send`, `POST /api/chat`, story dispatch, the Paperclip wake `/v1/chat/completions`, `POST /api/code`, `POST /api/computer/tasks` and `POST /api/cron/{name}/run` answer `423 {"error": "paused", since, detail}` (plus `by` and `reason` for an operator) and keep nothing; a cron job that falls due is skipped (status `skipped`, its next run moves on); no desktop task starts from any door (Telegram's `/computer yes` included); side model calls (titles, summaries, memory extraction, the curator) are not made; the WebSocket send gets an `error` frame of kind `paused`; reads and every stop route still work, and no slash command runs over the WebSocket. Survives a restart; an unreadable pause file means paused. `pause.json` is in the trusted-state floor, so the agent's shell cannot write or remove it (the gate, Seatbelt on macOS, the AppArmor profile on Linux; an installed AppArmor profile must be reloaded to get the rule) |
| PUT | `/api/pause` | Pause everything. Operator (the API token or an owner device); a scoped device gets `403 operator_only`. Body `{reason?}`. Writes the state to disk first, withdraws every pending approval, cancels every turn running in the daemon (the WebSocket, the REST chat routes, `/v1`, Telegram, Slack and Discord), stops desktop tasks, tasks and workers, and pauses (keeps) every coding run. A worker or coding run, a process of its own, also stops at its next round, and one that cannot reach the pause file's folder counts as paused. A pause stops what the daemon runs: a process the model has already detached from its shell (`nohup`, `setsid`) is outside it, and a process the model starts itself can be pointed at another pause file. Answers `{paused: true, since, by, reason, persisted, stopped: {turns, desktop_tasks, tasks, coding_runs, approvals_withdrawn}}` and broadcasts `paused_changed` `{paused, since}` (who and why are on `/api/status`). A new pause also pushes one alert, "Prometheus paused" with who paused (never why, and no category), to each owner device with no live connection; a second call pushes nothing. `oara doctor` has a Pause row. The pause holds even if the file cannot be written; `persisted: false` then says it will not survive a restart. Idempotent: a second call is the same pause (same `since`). While paused, `POST /api/chat/send`, `POST /api/chat`, story dispatch, the Paperclip wake `/v1/chat/completions`, `POST /api/code`, `POST /api/computer/tasks` and `POST /api/cron/{name}/run` answer `423 {"error": "paused", since, detail}` (plus `by` and `reason` for an operator) and keep nothing; a cron job that falls due is skipped (status `skipped`, its next run moves on); no desktop task starts from any door (Telegram's `/computer yes` included); side model calls (titles, summaries, memory extraction, the curator) are not made; the WebSocket send gets an `error` frame of kind `paused`; reads and every stop route still work, and no slash command runs over the WebSocket. Survives a restart; an unreadable pause file means paused. `pause.json` is in the trusted-state floor, so the agent's shell cannot write or remove it (the gate, Seatbelt on macOS, the AppArmor profile on Linux; an installed AppArmor profile must be reloaded to get the rule) |
| GET | `/api/pause` | Whether everything is paused: `{paused, since}`. Any valid credential, scoped devices included; never who or why (those are on `/api/status`, operator-only) |
| DELETE | `/api/pause` | Resume. The owner can also pause and resume from their own Telegram (`/pause [reason]`, `/resume`); nobody else can use those commands. **A person only**: a device carrying the person mark, which the owner sets in their own Telegram (`/person allow <device id>`, removed with `/person disallow <device id>`, listed with `/person`). The mark does nothing but allow resume: it is not the computer-use mark, no REST route sets it, and a held device cannot carry it. Anything else gets `403 person_required`: the API token, an open daemon, and any device without the mark, an owner device included (the token can mint one on this machine). Mark a device that is NOT on the daemon's own machine (your phone, say): a client on that machine keeps its token where the agent's shell could reach it if a floor were down, and the mark would then let the agent resume. Starts nothing: interrupted turns stay interrupted, coding runs stay paused until resumed one by one (`/api/code/{id}/resume`) |
| GET | `/api/packs` | Discovered packs with load/refuse state, refusal reasons, quarantined-draft ids, and panel declarations. `wired: false` means the pack loader didn't run this boot (the bare `web` entrypoint), distinct from "no packs installed" |
Expand Down
8 changes: 6 additions & 2 deletions src/prometheus/cli/doctor.py
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ class existed (daemon startup check + /doctor Telegram command) but had
ADVERTISED_TOOLS_ROW,
DiagnosticCheck,
always_loaded_case,
check_pause,
check_router,
yaml_error_summary,
)
Expand Down Expand Up @@ -1600,6 +1601,7 @@ def run_extended_checks(
check_memory_extraction(config),
check_whisper(config),
*check_voice_remotes(config, timeout=timeout),
check_pause(),
]


Expand Down Expand Up @@ -1629,9 +1631,11 @@ async def _scan_and_diagnose():
# per-gateway checks (SPRINT G3). "Router" is the same
# check_router row the extended checks already carry, and
# "Advertised tools" is check_advertised_tools' row, which adds
# the count of tools actually offered to the same case.
# the count of tools actually offered to the same case. "Pause" is
# check_pause, which the extended checks carry so it shows without
# the scan.
if check.name in ("Config", "Inference", "Model", "Whisper STT",
"Telegram", "Router", ADVERTISED_TOOLS_ROW):
"Telegram", "Router", "Pause", ADVERTISED_TOOLS_ROW):
continue
# Missing SOUL.md/AGENTS.md doesn't break the loop — the fast
# setup path deliberately skips identity. Warn, don't fail.
Expand Down
13 changes: 12 additions & 1 deletion src/prometheus/engine/pause.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
import asyncio
import json
import logging
import math
import os
import time
from dataclasses import dataclass
Expand Down Expand Up @@ -106,7 +107,17 @@ def read_file(path: Path) -> PauseInfo | None:
since, by, reason = data.get("since"), data.get("by"), data.get("reason", "")
if not isinstance(since, (int, float)) or isinstance(since, bool) or not isinstance(by, str):
return _unreadable("bad fields")
return PauseInfo(since=float(since), by=by, reason=reason if isinstance(reason, str) else "")
try:
when = float(since)
except (OverflowError, ValueError): # an integer too large for a float
return _unreadable("bad time")
if not math.isfinite(when) or not 0 <= when < SINCE_MAX:
return _unreadable("bad time") # Infinity, NaN, negative, or past what a clock shows
return PauseInfo(since=when, by=by, reason=reason if isinstance(reason, str) else "")


#: Seconds since the epoch past which a ``since`` is nonsense (the year 5138): every clock function can show it.
SINCE_MAX = 1e11


def _write_file(path: Path, data: dict[str, Any]) -> None:
Expand Down
5 changes: 5 additions & 0 deletions src/prometheus/gateway/commands.py
Original file line number Diff line number Diff line change
Expand Up @@ -1227,6 +1227,11 @@ async def cmd_curator_run(*, dry_run: bool = False) -> str:
instance = get_curator()
if instance is None:
return "Curator not wired (check learning.curator_enabled in config)."
from prometheus.engine import pause as _pause

if _pause.current() is not None:
# Its non-model pass archives skill files: nothing runs while everything is paused.
return "Prometheus is paused. The curator runs again once it is resumed."
try:
run = await instance.run_once(dry_run=dry_run)
except Exception as exc:
Expand Down
Loading
Loading