From f21275f3326eff8e221cc031e72826c47da3cd3e Mon Sep 17 00:00:00 2001
From: Adeel Ahmad
Date: Thu, 15 Oct 2026 17:46:57 +0000
Subject: [PATCH] feat(settings): an Automations section for the stream of
activities
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Settings → Automations (under System) edits events.poll_seconds, how often
followers look for new activities when nothing wakes them, and
events.keep_days, how long the event log is kept. The API checks both as
whole numbers in range.
Co-Authored-By: Claude Opus 5.5 (1M context)
Claude-Session: https://claude.ai/code/session_01RFQUkVmALkdhRqXY1yFxW5
---
docs/automations.md | 6 +++--
docs/configuration.md | 11 +++++++-
fastapi_backend/app/domain/ops_tools.py | 1 +
fastapi_backend/app/domain/settings.py | 14 ++++++++++
fastapi_backend/tests/api/test_activities.py | 17 ++++++++++++
.../__tests__/settings-find.test.tsx | 9 ++++++-
.../components/settings/bodies.tsx | 12 +++++++++
nextjs-frontend/components/settings/find.ts | 12 ++++++++-
nextjs-frontend/components/settings/model.ts | 27 +++++++++++++++++++
.../components/settings/settings-shell.tsx | 2 ++
10 files changed, 106 insertions(+), 5 deletions(-)
diff --git a/docs/automations.md b/docs/automations.md
index d4413003b..0186a4a00 100644
--- a/docs/automations.md
+++ b/docs/automations.md
@@ -16,6 +16,7 @@ merged is called built.
| The timeline API (`GET /api/v1/activities`), the MCP tools `timeline` and `event_kinds`, the assistant's `timeline` | built |
| The shapes of triggers, joins, an If, policy and intents, checked (`app/domain/automation_spec.py`) | built |
| The action registry with risk from each action's effect, and one action, `log_line` (`app/domain/actions.py`) | built |
+| Settings → Automations: how often followers look and how long the event log is kept | built |
| Storing and running automations, schedules and timers, joins, the real actions, approvals, variables, the timeline page, the studio | planned |
## Contract
@@ -98,7 +99,7 @@ A kind belongs to the source named in its `source`, and a source may list more i
audience=None, owner=None, untrusted=None)`, which gives the id (`log-`). Emitting a `key` again changes
nothing and gives the first id, so a retry never doubles an activity. Inside `with events.caused_by({"automation":
4, "run": 51, "depth": 1}):` what is emitted carries that cause. It is read by `(logged_at, id)` and paged by
- `published`, and its rows are kept for `events.keep_days` (30).
+ `published`, and its rows are kept for `events.keep_days` (30; Settings → Automations).
### Following the stream
@@ -118,7 +119,8 @@ where the next look starts (`event_cursor:`, a position per source).
(an activity's id, say), with a `CREATE` of `event_claim:` only one process wins. `events.unclaimed(db,
consumer, keys)` lists the keys nobody has claimed yet, in one query. Claims go after a day.
- `events.emit` wakes the followers in its process; a follower waits between looks with `g = events.generation()`
- before the look and `events.wait(events.poll_seconds(cfg), stop, since=g)` after it (`events.poll_seconds`, 5).
+ before the look and `events.wait(events.poll_seconds(cfg), stop, since=g)` after it (`events.poll_seconds`, 5;
+ Settings → Automations).
### Timeline reads
diff --git a/docs/configuration.md b/docs/configuration.md
index 7f365fadb..50e1ab71f 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -111,7 +111,7 @@ provider and key, a local model, the AI assistant, search (word search and searc
video, OCR, faces and objects, [NSFW classification](nsfw.md), workers, sign-in, components (and the edition, full or
lean), access and embedding (whether other devices on the network reach Lens, embed frame ancestors, text and transcript
upload limit, allowed hosts, trusted proxies, session length), remote access, email, chat rooms, notifications,
-telemetry, the Fedora repository, sensors, file shares, uploads, storage, documents, API keys, and IIIF and metadata. The API
+automations, telemetry, the Fedora repository, sensors, file shares, uploads, storage, documents, API keys, and IIIF and metadata. The API
refuses an allowed-host list that leaves out the address you are using.
The sections are in groups: AI and search, Speech and voices, Media and documents, Chat and email, Security and
@@ -461,6 +461,15 @@ Where namespaces may send notifications ([Notifications](notifications.md)). Set
| `notifications.poll_seconds` | 5 | how often the notifier looks for news, 1–3600 |
| `notifications.max_attempts` | 6 | how many times a message is tried, 1–20 |
+## Automations
+
+The stream of activities automations follow ([Automations](automations.md#contract)). Settings → Automations:
+
+| Setting | Default | |
+|---|---|---|
+| `events.poll_seconds` | 5 | how often followers look for new activities when nothing wakes them, 1–3600 |
+| `events.keep_days` | 30 | how long activities with no row of their own (the event log) are kept, 1–3650 days |
+
## Trusted proxies
IP groups ([Access](access.md#ip-groups)) match the visitor's address. The server takes it from the connection or,
diff --git a/fastapi_backend/app/domain/ops_tools.py b/fastapi_backend/app/domain/ops_tools.py
index dbff3ef62..982a47e71 100644
--- a/fastapi_backend/app/domain/ops_tools.py
+++ b/fastapi_backend/app/domain/ops_tools.py
@@ -32,6 +32,7 @@
"ai",
"reports",
"notifications",
+ "events",
"workers",
"decisions",
"voice",
diff --git a/fastapi_backend/app/domain/settings.py b/fastapi_backend/app/domain/settings.py
index 61340331b..16270ea6f 100644
--- a/fastapi_backend/app/domain/settings.py
+++ b/fastapi_backend/app/domain/settings.py
@@ -55,6 +55,7 @@
# repo is a startup setting only (what gets installed isn't chosen in the web app)
"updates": ("check", "check_hours", "auto_install", "email"),
"activity": None,
+ "events": None,
"backups": None,
"encryption": None,
"fedora": None,
@@ -476,6 +477,8 @@ def _check(section, key, value, default):
return _updates_setting(key, value)
if section == "activity":
return _activity_setting(key, value)
+ if section == "events":
+ return _events_setting(key, value)
if section == "backups":
return _backup_setting(key, value)
if section == "fedora":
@@ -1014,6 +1017,17 @@ def _activity_setting(key, value):
raise ValueError(f"unknown setting activity.{key}")
+def _events_setting(key, value):
+ """The stream of activities automations follow (docs/automations.md)."""
+ limits = {"keep_days": (1, 3650, "a whole number of days"), "poll_seconds": (1, 3600, "a whole number of seconds")}
+ if key not in limits:
+ raise ValueError(f"unknown setting events.{key}")
+ lo, hi, what = limits[key]
+ if not (isinstance(value, int) and not isinstance(value, bool) and lo <= value <= hi):
+ raise ValueError(f"events.{key} is {what} from {lo} to {hi}")
+ return value
+
+
def _backup_setting(key, value):
from . import schedule
diff --git a/fastapi_backend/tests/api/test_activities.py b/fastapi_backend/tests/api/test_activities.py
index 6497007d4..f017db9a6 100644
--- a/fastapi_backend/tests/api/test_activities.py
+++ b/fastapi_backend/tests/api/test_activities.py
@@ -114,3 +114,20 @@ def look(): # the API's follower, or the worker's
look()
look()
assert sorted(handled) == sorted(new)
+
+
+def test_the_stream_is_set_up_in_the_web_app(app, client, db, cfg):
+ make_user(db, "root@x.io", "root password 1", admin=True)
+ h = login(client, "root@x.io", "root password 1")
+ assert events.section(app.state.settings.current()) == {"keep_days": 30, "poll_seconds": 5}
+ assert client.put("/api/v1/settings/events", json={"keep_days": 90, "poll_seconds": 2}, headers=h).status_code == 200
+ cfg = app.state.settings.current()
+ assert (events.section(cfg)["keep_days"], events.poll_seconds(cfg)) == (90, 2)
+ assert client.get("/api/v1/settings", headers=h).json()["events"]["values"] == {"keep_days": 90, "poll_seconds": 2}
+ for bad in ({"keep_days": 0}, {"poll_seconds": 3601}, {"keep_days": "30"}, {"poll_seconds": True}, {"tick": 1}):
+ assert client.put("/api/v1/settings/events", json=bad, headers=h).status_code == 400, bad
+ # the admin assistant reads and changes the same section
+ box = ai_tools.Toolbox(db, cfg, {"id": 1, "email": "root@x.io"}, set(), set(), {}, None, admin=True, act=True)
+ assert box.t_read_settings("events")[0]["values"] == {"keep_days": 90, "poll_seconds": 2}
+ assert box.t_change_settings("events", {"keep_days": 7})[0]["status"] == "done"
+ assert box.t_read_settings("events")[0]["values"]["keep_days"] == 7
diff --git a/nextjs-frontend/__tests__/settings-find.test.tsx b/nextjs-frontend/__tests__/settings-find.test.tsx
index c3255a7ce..5260cc263 100644
--- a/nextjs-frontend/__tests__/settings-find.test.tsx
+++ b/nextjs-frontend/__tests__/settings-find.test.tsx
@@ -2,7 +2,7 @@ import { fireEvent, render, screen, waitFor } from "@testing-library/react";
import "@testing-library/jest-dom";
import { findSettings, hitHref, SETTINGS_GROUPS } from "@/components/settings/find";
-import { SECTIONS } from "@/components/settings/model";
+import { fieldId, fieldsOf, SECTIONS } from "@/components/settings/model";
import { SettingsShell } from "@/components/settings/settings-shell";
import { TooltipProvider } from "@/components/ui/tooltip";
@@ -74,6 +74,13 @@ describe("finding a setting", () => {
expect(hits.some((h) => h.section === "transcription" && h.fields.some((f) => f.key === "engine"))).toBe(true);
});
+ it("finds the stream automations follow in Automations, under System", () => {
+ const hits = findSettings("activities", true);
+ const auto = hits.find((h) => h.section === "automations")!;
+ expect(auto.group).toBe("System");
+ expect(fieldsOf("automations").map((f) => fieldId(f))).toEqual(["events.poll_seconds", "events.keep_days"]);
+ });
+
it("finds only People for people who aren't admins", () => {
expect(findSettings("speak", false).map((h) => h.section)).toEqual(["speakers"]);
expect(findSettings("telegram", false)).toEqual([]);
diff --git a/nextjs-frontend/components/settings/bodies.tsx b/nextjs-frontend/components/settings/bodies.tsx
index 39e7317db..292d93185 100644
--- a/nextjs-frontend/components/settings/bodies.tsx
+++ b/nextjs-frontend/components/settings/bodies.tsx
@@ -469,6 +469,18 @@ export function SectionBody({ ctx }: { ctx: BodyCtx }) {
>
);
+ case "automations":
+ return (
+ <>
+
+
+
+
+
+ Agents read the same stream with the timeline tool (MCP and the assistant) or GET /api/v1/activities.
+
+ >
+ );
case "encryption":
return ;
case "backups":
diff --git a/nextjs-frontend/components/settings/find.ts b/nextjs-frontend/components/settings/find.ts
index 599d90bef..214be80ee 100644
--- a/nextjs-frontend/components/settings/find.ts
+++ b/nextjs-frontend/components/settings/find.ts
@@ -22,7 +22,17 @@ export const SETTINGS_GROUPS: { label: string; sections: SectionId[] }[] = [
{ label: "Files and devices", sections: ["storage", "shares", "smb", "nfs", "fedora", "sensors"] },
{
label: "System",
- sections: ["updates", "backups", "components", "workers", "logs", "telemetry", "analytics", "startup"],
+ sections: [
+ "updates",
+ "backups",
+ "components",
+ "workers",
+ "automations",
+ "logs",
+ "telemetry",
+ "analytics",
+ "startup",
+ ],
},
];
diff --git a/nextjs-frontend/components/settings/model.ts b/nextjs-frontend/components/settings/model.ts
index 5c4e55257..44342f563 100644
--- a/nextjs-frontend/components/settings/model.ts
+++ b/nextjs-frontend/components/settings/model.ts
@@ -72,6 +72,7 @@ export type SectionId =
| "video"
| "nsfw"
| "workers"
+ | "automations"
| "components"
| "access"
| "remote-access"
@@ -389,6 +390,13 @@ export const SECTIONS: SectionSpec[] = [
backend: ["iiif"],
description: "How assets are published as IIIF Manifests and Collections.",
},
+ {
+ id: "automations",
+ label: "Automations",
+ backend: ["events"],
+ description:
+ "The stream of activities automations follow (new assets and what else happens in Lens): how often followers look for new ones, and how long activities with no row of their own are kept.",
+ },
{
id: "startup",
label: "Set at startup",
@@ -2670,6 +2678,25 @@ export const FIELDS: FieldSpec[] = [
max: 20,
hint: "A failed send waits 30 seconds, then four times longer each time, up to 6 hours",
},
+ // Automations (the stream of activities)
+ {
+ section: "events",
+ key: "poll_seconds",
+ label: "Look for new activities every (seconds)",
+ kind: "int",
+ min: 1,
+ max: 3600,
+ hint: "New assets wake followers on this server at once; this is how often they look anyway",
+ },
+ {
+ section: "events",
+ key: "keep_days",
+ label: "Keep logged activities (days)",
+ kind: "int",
+ min: 1,
+ max: 3650,
+ hint: "Activities with no row of their own, such as an automation’s; new assets and other rows stay as long as they do",
+ },
// Usage analytics (Google Analytics opt-in)
{
section: "analytics",
diff --git a/nextjs-frontend/components/settings/settings-shell.tsx b/nextjs-frontend/components/settings/settings-shell.tsx
index c26e2af29..919b349ef 100644
--- a/nextjs-frontend/components/settings/settings-shell.tsx
+++ b/nextjs-frontend/components/settings/settings-shell.tsx
@@ -46,6 +46,7 @@ import {
RefreshCw,
Network,
ScrollText,
+ Workflow,
} from "lucide-react";
import Link from "next/link";
import { useRouter, useSearchParams } from "next/navigation";
@@ -87,6 +88,7 @@ const ICON: Record = {
video: Clapperboard,
nsfw: EyeOff,
workers: Cpu,
+ automations: Workflow,
components: PackageCheck,
access: ShieldCheck,
"remote-access": Cloud,