From c6916f4fe1b3fbabca1d46b166864a1796e530ae Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sat, 17 Oct 2026 09:35:57 +0000 Subject: [PATCH 1/4] feat(schedules): one Schedules page for every routine, automation schedule and the backup Lens's crontab: GET/PATCH /api/v1/schedules and POST /run, MCP tools schedules, set_schedule and run_schedule, and an Automate > Schedules page to switch, re-time and run anything on a clock. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01NwZdhpvjjidN5Y45CLSi8m --- README.md | 18 +- docs/api.md | 13 + docs/automations.md | 3 + docs/mcp.md | 3 + docs/processing.md | 3 + docs/requirements.md | 1 + docs/schedules.md | 55 ++ fastapi_backend/app/api/mcp_tools.py | 60 +++ fastapi_backend/app/api/v1/router.py | 2 + .../app/api/v1/routes/schedules.py | 101 ++++ fastapi_backend/app/domain/schedules.py | 240 +++++++++ fastapi_backend/app/schemas/schedules.py | 67 +++ fastapi_backend/tests/api/test_mcp.py | 2 + fastapi_backend/tests/api/test_schedules.py | 164 ++++++ mkdocs.yml | 1 + nextjs-frontend/__tests__/navigation.test.ts | 8 + .../__tests__/schedules-model.test.ts | 105 ++++ .../__tests__/schedules-page.test.tsx | 165 ++++++ nextjs-frontend/app/(app)/schedules/page.tsx | 11 + nextjs-frontend/app/openapi-client/index.ts | 24 + nextjs-frontend/app/openapi-client/sdk.gen.ts | 81 +++ .../app/openapi-client/types.gen.ts | 300 +++++++++++ .../components/app-shell/nav-config.ts | 3 + .../components/routines/routine-editor.tsx | 100 +--- .../components/routines/schedule-fields.tsx | 117 +++++ nextjs-frontend/components/schedules/model.ts | 102 ++++ .../components/schedules/schedules-page.tsx | 389 ++++++++++++++ nextjs-frontend/openapi.json | 492 ++++++++++++++++++ 28 files changed, 2526 insertions(+), 104 deletions(-) create mode 100644 docs/schedules.md create mode 100644 fastapi_backend/app/api/v1/routes/schedules.py create mode 100644 fastapi_backend/app/domain/schedules.py create mode 100644 fastapi_backend/app/schemas/schedules.py create mode 100644 fastapi_backend/tests/api/test_schedules.py create mode 100644 nextjs-frontend/__tests__/schedules-model.test.ts create mode 100644 nextjs-frontend/__tests__/schedules-page.test.tsx create mode 100644 nextjs-frontend/app/(app)/schedules/page.tsx create mode 100644 nextjs-frontend/components/routines/schedule-fields.tsx create mode 100644 nextjs-frontend/components/schedules/model.ts create mode 100644 nextjs-frontend/components/schedules/schedules-page.tsx diff --git a/README.md b/README.md index 130d915ac..9d4fa2674 100644 --- a/README.md +++ b/README.md @@ -148,14 +148,16 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p the assistant, and people review on the Timeline page (and Latest on Home), marking what they've seen. Automations act on that stream, on a schedule, at a time or when their own webhook is called: they test conditions, then tell you in your own chat app, ask the model or the agent, use a tool, call a web address (its credentials kept sealed), run a - workflow, pipeline or routine, or change assets and notes. A Classify node in a workflow sorts an asset into labels, - content types or topics, acting only on a sure answer. Anything that reaches outside Lens or changes more than what - set it off asks first, until you let it run on its own: on the Approvals page or, for a change inside Lens, with a yes - in the chat it told you in; agents can decline an approval but never give one. Each automation has limits and budgets, - and agents make, try and run them over MCP and in the assistant, or draft one from a sentence; the studio to draw them - in the web app is planned. ([Processing](docs/processing.md#workflows-and-the-canvas), - [notifications](docs/notifications.md), [automations](docs/automations.md), - [approvals](docs/automations.md#approvals), [timeline](docs/timeline.md); [checks](docs/requirements.md#automate-it)) + workflow, pipeline or routine, or change assets and notes. The Schedules page is Lens's crontab: every routine, + automation schedule and the backup in one list with when each runs next and last, to switch, re-time or run now, and + agents do the same over the API and MCP. A Classify node in a workflow sorts an asset into labels, content types or + topics, acting only on a sure answer. Anything that reaches outside Lens or changes more than what set it off asks + first, until you let it run on its own: on the Approvals page or, for a change inside Lens, with a yes in the chat it + told you in; agents can decline an approval but never give one. Each automation has limits and budgets, and agents + make, try and run them over MCP and in the assistant, or draft one from a sentence; the studio to draw them in the web + app is planned. ([Processing](docs/processing.md#workflows-and-the-canvas), [notifications](docs/notifications.md), + [automations](docs/automations.md), [approvals](docs/automations.md#approvals), [schedules](docs/schedules.md), + [timeline](docs/timeline.md); [checks](docs/requirements.md#automate-it)) - **See what it costs.** An activity ledger of every model call, with reports, charts and budgets that cap spending. Setup asks for one overall budget after a cloud model, with a soft limit that warns and a hard limit that stops paid calls. A meter in the top bar shows spend against the budget, and the Costs page breaks it down by day, model and diff --git a/docs/api.md b/docs/api.md index 02e4b568f..ec5472841 100644 --- a/docs/api.md +++ b/docs/api.md @@ -364,6 +364,19 @@ starts one now and `runs` lists its last runs. A run held over a budget is run o takes back every graph change a run made. `GET /graph-changes` lists the changes to the entities of namespaces you can read, newest first; editors `accept`, `dismiss` or `undo` one ([Graph history](graph-history.md)). +## schedules + +``` +GET /api/v1/schedules +GET /api/v1/schedules/{id} +PATCH /api/v1/schedules/{id} +POST /api/v1/schedules/{id}/run +``` + +Everything that runs on a clock, in one list ([Schedules](schedules.md)): routines and the scheduled backup for +admins, and the schedule and at triggers of the automations you manage. An id is `routine:3`, +`automation:4:morning` or `backups`; `PATCH` takes `cron`, `at`, `timezone` and `enabled`, and `run` runs it now. + ## namespaces ``` diff --git a/docs/automations.md b/docs/automations.md index 2e9fb09db..f68bd4f89 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -682,6 +682,9 @@ automations}`, for a badge). Time is a trigger and a step: "every weekday at 7:00", "at 9:00 on the 20th", "30 minutes before a calendar event", "wait 2 hours, then...", and the clock behind a join's "if no reply within 2 days". All of it rests on timers. +Every automation's schedule and at trigger is also a row on the [Schedules](schedules.md) page, next to the routines +and the backup, where it is switched, re-timed and run now. + ### Timers Built (`app/domain/timers.py`). A timer is one row per key in the `timer` table: when it is due, what runs then (its diff --git a/docs/mcp.md b/docs/mcp.md index 261fb36c8..7092108a8 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -117,6 +117,9 @@ For an app that speaks OpenAI's API rather than MCP, the namespace can also answ | `save_automation` | make an automation, or change one: name, triggers, its If (`condition`), its graph, namespaces, limits; a new one is saved switched off unless `enabled` is true. Problems come back in plain words; a node never runs on its own from here. Needs a write-scope token | | `test_automation` | try a saved automation or a draft on an activity or a kind's sample: whether its If passes and what each action would do, keeping and sending nothing | | `run_automation` | run an automation now, on an activity or the newest one its triggers listen for; limits and budgets apply. Needs a write-scope token | +| `schedules` | everything that runs on a clock, soonest first ([Schedules](schedules.md)): routines and the scheduled backup (admins) and the schedule and at triggers of the person's automations, each with its id, when it runs in words and as cron, its time zone, its next and last run and whether it's on; `kind` for one kind | +| `set_schedule` | change when one of those runs (`cron`, an at trigger's `at`, `timezone`), take its schedule away (`by_hand`), or switch it on or off (an automation's switch is the whole automation's). Needs a write-scope token | +| `run_schedule` | run one now, even when it's off: a routine within half a minute, an automation as its trigger would, the backup now; budgets apply. Needs a write-scope token | | `event_kinds` | the kinds of activity there are: label, source, parent and children, a schema with each field's title, the fields holding outside text, and a sample | | `automation_vars` | the values automations keep between runs ([Saved variables](automations.md#saved-variables)): an automation's own or a namespace's, each with who set it last and whether it came from outside text. Needs access to the automation or the namespace | | `set_automation_vars` | set or clear an automation's or a namespace's variables (`changes`, a JSON object; null clears one). Needs a write-scope token and the right to change the automation, or editor access to the namespace | diff --git a/docs/processing.md b/docs/processing.md index 548206785..305373489 100644 --- a/docs/processing.md +++ b/docs/processing.md @@ -732,6 +732,9 @@ now. Every 30 seconds, `lens worker` checks (and so does the API process when it never started twice at once, and one started in two processes runs once. Each run keeps what every action did and a log. +The [Schedules](schedules.md) page lists every routine next to the automations' schedules and the backup, to switch, +re-time and run each from one place. + ### Organising the graph A workflow's scope is assets (above), the graph, or an event: an automation's workflow, run by its automation diff --git a/docs/requirements.md b/docs/requirements.md index aed08229d..62e0a9c6d 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -173,6 +173,7 @@ request, to another check that proves the same thing; loosening a requirement or | Pipelines and workflows on a canvas | [test_workflows.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_workflows.py) `test_workflows_run_in_pipelines_drawn_as_graphs`; [workflow-canvas.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/workflow-canvas.test.ts); [journeys.mjs](https://github.com/adeelahmad/lense/blob/main/ci/clicks/journeys.mjs) `pipeline-create`, `workflow-create` | | A Classify node in workflows chooses from labels, content types or topics, and acting on a sure answer keeps something | [test_classify.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_classify.py) `test_a_workflow_classifies`; [workflow-flow.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/workflow-flow.test.ts) `chooses from labels, content types or topics, and acting on a sure answer keeps something` | | Routines on a schedule | [test_routines.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_routines.py) `test_routines_are_checked_and_run_when_due`, `test_schedules`; [journeys.mjs](https://github.com/adeelahmad/lense/blob/main/ci/clicks/journeys.mjs) `routine-create`; [baseline.json](https://github.com/adeelahmad/lense/blob/main/ci/clicks/baseline.json) `routine-create` ≤ 2 clicks | +| Everything that runs on a clock (routines, automations' schedule and at triggers, the backup) in one Schedules list, switched, re-timed and run from it, by people and by agents over the API and MCP | [test_schedules.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_schedules.py) `test_one_list_holds_every_routine_automation_schedule_and_the_backup`, `test_schedules_are_changed_switched_and_run_from_the_list`, `test_agents_list_change_and_run_schedules_over_mcp`; [schedules-page.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/schedules-page.test.tsx) `lists every routine, automation schedule and the backup, each linking to its own page`, `switches one off, runs one now and changes when one runs, from the list` | | Batch runs over a collection | [test_batches.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_batches.py) `test_collections_and_batches` | | Notifications to webhooks, Slack, Discord and Matterbridge | [test_notifications.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_notifications.py) `test_owners_manage_targets_and_a_test_is_signed`, `test_runs_that_end_are_sent_once_to_matterbridge` | | Everything that happens is kept as W3C Activity Streams activities, read by agents through the API, MCP and the assistant | [test_events.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_events.py) `test_activities_have_one_shape`; [test_activities.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_activities.py) `test_the_timeline_lists_new_assets_newest_first`, `test_agents_read_the_timeline_too`; [test_news_feed_source.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_news_feed_source.py) `test_a_news_feed_as_a_source` | diff --git a/docs/schedules.md b/docs/schedules.md new file mode 100644 index 000000000..c21804c94 --- /dev/null +++ b/docs/schedules.md @@ -0,0 +1,55 @@ +# Schedules + +Status: built. The Schedules page (Automate → Schedules) is Lens's crontab: everything that runs on a clock, in one +list, soonest first, with a switch, Run now and a way to change when it runs. Agents get the same list and the same +changes over the API and MCP. + +## What is on it + +| Row | What it is | Who sees it | +| --- | --- | --- | +| A routine | its schedule (five-field cron, in a time zone), or "only when run by hand" ([Routines](processing.md#routines)) | admins | +| An automation's schedule or at trigger | one row per trigger that runs on the clock: "every weekday at 07:00", or "once, on Mon 2 Nov at 07:30" ([Time](automations.md#time)) | admins, and the editors who manage the automation | +| The backup | Settings › Backups' schedule, or "not scheduled" ([Backups](database.md#backups)) | admins | + +Each row says when it runs in words and as cron with its time zone, when it runs next, how its last run went and when, +and whether it is on. Its name opens the routine, the automation or Settings › Backups. An automation's other triggers +(something happening, a webhook, by hand) aren't on the clock, so they stay on the automation's own page. + +Nothing is kept for the list: it is read from the routines, the automations' timers and the backup setting each time, +so it always says what Lens will do. + +## Changing one + +- **The switch** turns a routine or the backup on or off. An automation's switch turns the whole automation on or + off, whatever starts it. The backup has no off of its own: off clears its schedule, and switching it on asks for one. +- **Change when it runs** (the pencil) picks every hour, every day at 03:00, weekdays at 09:00, or a cron of your own, + in any time zone, and shows the next five times before you save; Enter saves. A routine can also run only by hand + and the backup can have no schedule. An at trigger takes a new date and time. +- **Run now** runs it even when it's off: a routine when the scheduler next looks (within half a minute), an + automation here and now as its trigger would when its time comes (its If, limits and budgets apply, and actions + that ask first wait for your pick), the backup now. A routine over one of its budgets asks before it runs anyway. + +Every change goes through the routine's, the automation's or the setting's own checks and audit log, so a schedule +that never runs, an unknown time zone or an automation its person can no longer run is refused with the reason. + +## For agents + +``` +GET /api/v1/schedules +GET /api/v1/schedules/{id} +PATCH /api/v1/schedules/{id} {cron?, at?, timezone?, enabled?} +POST /api/v1/schedules/{id}/run {over_budget?} +``` + +A schedule's id says what it is: `routine:3`, `automation:4:morning` (the automation and its trigger's `as`) or +`backups`. `cron: null` runs a routine only by hand and stops scheduled backups. Over MCP, `schedules` lists them +(optionally one kind), `set_schedule` changes one (`by_hand: true` takes the schedule away) and `run_schedule` runs +one; the two that change something need a token with the write scope. Someone who isn't an admin gets 404 for a +routine or the backup, and for an automation they don't manage, so ids don't leak. + +## Refine later + +- Add a schedule to an automation that has none, from this page. +- The assistant's own tools for schedules (agents use MCP today). +- Other things that repeat on their own clock (source polling, sensor digests, update checks) as read-only rows. diff --git a/fastapi_backend/app/api/mcp_tools.py b/fastapi_backend/app/api/mcp_tools.py index e6ca14a38..202200a9e 100644 --- a/fastapi_backend/app/api/mcp_tools.py +++ b/fastapi_backend/app/api/mcp_tools.py @@ -37,6 +37,7 @@ from app.api.v1.routes import notebook as note_routes from app.api.v1.routes import recordings as recording_routes from app.api.v1.routes import routines as routine_routes +from app.api.v1.routes import schedules as schedule_routes from app.api.v1.routes import search as search_routes from app.api.v1.routes import topics as topic_routes from app.domain import ( @@ -88,6 +89,7 @@ from app.schemas.chats import ChatSummary from app.schemas.entities import EntityHide, EntityList, EntityRename, EntityRetype, EntityUpdate from app.schemas.notebook import NotePage +from app.schemas.schedules import ScheduleChange, ScheduleRun from app.schemas.search import SearchResults from app.schemas.topics import TopicMerge, TopicUpdate @@ -2965,3 +2967,61 @@ def run_automation(ctx: Context, automation_id: int, activity: str | None, trigg _writer(ctx, "run automations") body = AutomationRunNow(activity=activity, **{"as": trigger}) return automation_routes.run_automation(automation_id, ctx.user, ctx.acl, ctx.db, ctx.cfg, body).model_dump() + + +# ---------- schedules ---------- +@tool( + "schedules", + "What runs on a clock", + "Everything in Lens that runs on a clock, like a crontab, soonest first: routines and the scheduled backup " + "(admins) and the schedule and at triggers of your automations. Each has its id (for set_schedule and " + "run_schedule), when it runs in words and as cron, its time zone, when it runs next and last, how that went and " + "whether it's on.", + Arg("kind", "string", "only routines, automations or the backup", enum=("routine", "automation", "backups")), +) +def schedules(ctx: Context, kind: str | None) -> dict[str, Any]: + got = schedule_routes.list_schedules(ctx.user, ctx.acl, ctx.db, ctx.cfg) + return {"schedules": [s.model_dump(exclude_none=True) for s in got.schedules if kind in (None, s.kind)]} + + +@tool( + "set_schedule", + "Change a schedule", + "Change when something runs on a clock, or switch it on or off: a routine, an automation's schedule or at " + "trigger, or the scheduled backup, by its id from schedules. Give only what changes. Switching an automation's " + "schedule switches the whole automation. Routines and the backup are for admins. Needs a token with the write scope.", + Arg("schedule_id", "string", "routine:3, automation:4:morning or backups (from schedules)", required=True, max_length=80), + Arg("cron", "string", "when it repeats: five-field cron (minute hour day month weekday) like 0 7 * * 1-5, or @daily", max_length=100), + Arg("at", "string", "a new time for an automation's at trigger, like 2026-11-02T07:30", max_length=40), + Arg("timezone", "string", "its time zone, like Europe/London", max_length=60), + Arg("by_hand", "boolean", "true takes the schedule away: a routine then runs only by hand, the backup stops"), + Arg("enabled", "boolean", "switch it on (it runs on its own) or off"), + writes=True, +) +def set_schedule( + ctx: Context, schedule_id: str, cron: str | None, at: str | None, timezone: str | None, by_hand: bool | None, enabled: bool | None +) -> dict[str, Any]: + _writer(ctx, "change schedules") + given: dict[str, Any] = {k: v for k, v in (("cron", cron), ("at", at), ("timezone", timezone), ("enabled", enabled)) if v is not None} + if by_hand: + if cron: + raise ToolError("give a cron or by_hand, not both") + given["cron"] = None + if not given: + raise ToolError("say what changes: cron, at, timezone, by_hand or enabled") + got = schedule_routes.change_schedule(schedule_id, ScheduleChange(**given), ctx.request, ctx.user, ctx.acl, ctx.db, ctx.cfg) + return got.model_dump(exclude_none=True) + + +@tool( + "run_schedule", + "Run a schedule now", + "Run something that runs on a clock now, even when it's off, by its id from schedules: a routine starts within half " + "a minute, an automation runs here and now as its trigger would when its time comes, the backup is taken now. A run " + "over a budget is refused (routines) or held for the person's pick (automations). Needs a token with the write scope.", + Arg("schedule_id", "string", "routine:3, automation:4:morning or backups (from schedules)", required=True, max_length=80), + writes=True, +) +def run_schedule(ctx: Context, schedule_id: str) -> dict[str, Any]: + _writer(ctx, "run schedules") + return schedule_routes.run_schedule(schedule_id, ctx.user, ctx.acl, ctx.db, ctx.cfg, ScheduleRun()).model_dump(exclude_none=True) diff --git a/fastapi_backend/app/api/v1/router.py b/fastapi_backend/app/api/v1/router.py index 701471d63..c9ac533ef 100644 --- a/fastapi_backend/app/api/v1/router.py +++ b/fastapi_backend/app/api/v1/router.py @@ -56,6 +56,7 @@ recordings, requests, routines, + schedules, search, searches, sensors, @@ -144,6 +145,7 @@ views, notifications, routines, + schedules, sensors, shares, import_hooks, diff --git a/fastapi_backend/app/api/v1/routes/schedules.py b/fastapi_backend/app/api/v1/routes/schedules.py new file mode 100644 index 000000000..6b2177ea9 --- /dev/null +++ b/fastapi_backend/app/api/v1/routes/schedules.py @@ -0,0 +1,101 @@ +"""Schedules (docs/schedules.md): everything that runs on a clock, in one list, like a crontab: routines (admins), +automations' schedule and at triggers (the automations you manage) and the scheduled backup (admins). Changing or +running one goes through its routine's, automation's or setting's own route, with its checks and audit.""" + +from __future__ import annotations + +from typing import Any + +from fastapi import APIRouter, HTTPException, Request + +from app.api.deps import Acl, Cfg, CurrentUser, Db, Principal, Writer, domain_errors +from app.api.v1.routes import admin as admin_routes +from app.api.v1.routes import automations as automation_routes +from app.api.v1.routes import routines as routine_routes +from app.api.v1.routes import updates as update_routes +from app.domain import auth, schedules +from app.schemas.automations import AutomationSwitch, AutomationUpdate +from app.schemas.routines import RoutineRunRequest, RoutineUpdate +from app.schemas.schedules import Schedule, ScheduleCatalog, ScheduleChange, ScheduleRun, ScheduleStarted + +router = APIRouter(prefix="/schedules", tags=["schedules"]) + + +def _editable(db: Any, user: Principal, acl: Any) -> list[int]: + return automation_routes._editable(db, user, acl) + + +def _one(db: Any, cfg: Any, user: Principal, acl: Any, sid: str) -> dict[str, Any]: + """The schedule, if this person manages it (404 otherwise, so ids don't leak).""" + try: + return schedules.one(db, cfg, sid, user.admin, _editable(db, user, acl)) + except KeyError: + raise HTTPException(404, "not found") from None + + +@router.get("") +def list_schedules(user: CurrentUser, acl: Acl, db: Db, cfg: Cfg) -> ScheduleCatalog: + """Everything that runs on a clock that you manage, soonest first: for admins every routine (those run only by + hand too) and the scheduled backup; for everyone the schedule and at triggers of their automations. Each with + when it runs in words, its next and last run, how that went and whether it's on.""" + return ScheduleCatalog(schedules=[Schedule(**r) for r in schedules.listing(db, cfg, user.admin, _editable(db, user, acl))]) + + +@router.get("/{sid}") +def get_schedule(sid: str, user: CurrentUser, acl: Acl, db: Db, cfg: Cfg) -> Schedule: + return Schedule(**_one(db, cfg, user, acl, sid)) + + +@router.patch("/{sid}") +def change_schedule(sid: str, body: ScheduleChange, request: Request, user: Writer, acl: Acl, db: Db, cfg: Cfg) -> Schedule: + """Change when it runs or switch it on or off; give only what changes. A routine's `cron: null` runs it only by + hand. Switching an automation's schedule switches the whole automation (every trigger it has). Switching the + backup off clears backups.schedule; switching it on needs a cron.""" + row = _one(db, cfg, user, acl, sid) + given = body.model_dump(exclude_unset=True) + if not given: + raise HTTPException(400, "say what changes: cron, at, timezone or enabled") + kind, xid, alias = schedules.parse_id(sid) + with domain_errors(): + if kind == "routine": + if "at" in given: + raise ValueError("a routine repeats on a schedule (cron); it has no single time") + changes = {"schedule": given["cron"]} if "cron" in given else {} + changes |= {k: given[k] for k in ("timezone", "enabled") if given.get(k) is not None} + routine_routes.update_routine(xid, RoutineUpdate(**changes), user, db) + elif kind == "automation": + if any(given.get(k) is not None for k in ("cron", "at", "timezone")): + a = automation_routes._mine(db, user, acl, xid) + triggers = schedules.retimed(a, alias, given.get("cron"), given.get("at"), given.get("timezone")) + automation_routes.update_automation(xid, AutomationUpdate(triggers=triggers), user, acl, db, cfg) + elif "cron" in given or "at" in given: + raise ValueError("an automation's schedule needs a cron (or an at trigger a time); switch it off instead") + if given.get("enabled") is not None: + automation_routes.enable_automation(xid, AutomationSwitch(on=given["enabled"]), user, acl, db, cfg) + else: + if "at" in given: + raise ValueError("the backup repeats on a schedule (cron); it has no single time") + changes = schedules.backup_settings(given, row.get("cron")) + if changes: + admin_routes.update_settings("backups", changes, user, request, db) + return Schedule(**_one(db, request.app.state.settings.current(), user, acl, sid)) + + +@router.post("/{sid}/run") +def run_schedule(sid: str, user: Writer, acl: Acl, db: Db, cfg: Cfg, body: ScheduleRun | None = None) -> ScheduleStarted: + """Run it now, even when it's off: a routine as soon as the scheduler next looks (within half a minute), an + automation here and now as its trigger would when its time comes, the backup now (it can take a while). A run over + a budget is refused (routines: 409) or held for your pick (automations) unless over_budget is true.""" + body = body or ScheduleRun() + _one(db, cfg, user, acl, sid) + kind, xid, alias = schedules.parse_id(sid) + if kind == "routine": + routine_routes.run_routine(xid, RoutineRunRequest(over_budget=body.over_budget), user, db, cfg) + return ScheduleStarted(status="asked", why="it starts within half a minute") + if kind == "automation": + with domain_errors(): + got = schedules.run_automation(db, cfg, xid, alias, user.email, body.over_budget) + auth.audit(db, user.as_audit(), "automation.run", f"automation:{xid}", {"run": got["run"], "trigger": alias}) + return ScheduleStarted(**got) + taken = update_routes.take_backup(user, db, cfg) + return ScheduleStarted(status="done", backup=taken.name) diff --git a/fastapi_backend/app/domain/schedules.py b/fastapi_backend/app/domain/schedules.py new file mode 100644 index 000000000..2c2ff7e24 --- /dev/null +++ b/fastapi_backend/app/domain/schedules.py @@ -0,0 +1,240 @@ +"""Schedules (docs/schedules.md): everything in Lens that runs on a clock, in one list, like a crontab. A schedule is +one of: + +- a routine (`routine:`): its cron schedule and time zone, or none when it runs only by hand (routines.py); +- an automation's schedule or at trigger (`automation::`): the timer that fires it (timers.py); +- the scheduled backup (`backups`): backups.schedule (backups.py). + +Each comes as a row saying when it runs in words, when it runs next and last, how the last run went and whether it is +on. Nothing is kept here: changing a schedule changes the routine, automation or setting it belongs to, through that +one's own checks, so the list is always what Lens will do. +""" + +from __future__ import annotations + +import datetime as dt +import re + +from . import automations, backups, routines, schedule, timers + +KINDS = ("routine", "automation", "backups") +ID_RX = re.compile(r"^(?:routine:(\d+)|automation:(\d+):([a-z][a-z0-9_]{0,39})|backups)$") +CLOCK = ("schedule", "at") # an automation's triggers that run on a clock + + +def parse_id(sid): + """(kind, id, trigger) from a schedule's id: routine:3, automation:4:morning or backups; KeyError otherwise.""" + m = ID_RX.match(sid or "") + if not m: + raise KeyError(sid) + if m.group(1): + return "routine", int(m.group(1)), None + if m.group(2): + return "automation", int(m.group(2)), m.group(3) + return "backups", None, None + + +# ---------- one row per schedule ---------- +def routine_row(r): + """A routine (routines.get's view) as a schedule.""" + on = bool(r.get("enabled")) + return { + "id": f"routine:{r['id']}", + "kind": "routine", + "name": r["name"], + "trigger": None, + "on": "schedule" if r.get("schedule") else "manual", + "cron": r.get("schedule"), + "at": None, + "timezone": r.get("timezone") or "UTC", + "text": r.get("schedule_text") or "only when run by hand", + "enabled": on, + "state": "running" if r.get("running") else ("on" if on and r.get("schedule") else "off"), + "next_run_at": r.get("next_run_at") if on and r.get("schedule") else None, + "last_run_at": r.get("last_run_at"), + "last_status": r.get("last_status"), + "running": bool(r.get("running")), + "href": f"/routines/{r['id']}", + "namespace_names": r.get("namespace_names"), + "note": None if r.get("schedule") else "Runs only when someone presses Run now; give it a schedule to run on its own.", + } + + +def _last_run(db, aid, alias, timer): + """How an automation's clock trigger last went: its newest run, else the timer's last firing (a run its If + skipped or a limit stopped leaves no run).""" + run = db.one( + "SELECT id, status, started_at FROM automation_run WHERE automation = $a AND trigger = $t ORDER BY id DESC LIMIT 1", + a=aid, + t=alias, + ) + last = (timer or {}).get("last") or {} + fired = last.get("fired_at") + if run and (not fired or (run.get("started_at") or "") >= fired[:19]): + return run.get("started_at"), run.get("status") + if fired: + return fired, "done" if last.get("ok", True) else "failed" + return None, None + + +def automation_rows(db, a, now=None): + """An automation's schedule and at triggers (automations.view), one row each.""" + out = [] + clock = [t for t in a.get("triggers") or [] if t.get("on") in CLOCK] + if not clock: + return out + states = timers.clock_state(db, a, now) + for t in clock: + alias = t["as"] + st = states.get(alias) or {"status": "off", "at": None} + key = f"{'sched' if t['on'] == 'schedule' else 'at'}-{a['id']}-{alias}" + last_at, last_status = _last_run(db, a["id"], alias, timers.get(db, key)) + tz = t.get("timezone") or "UTC" + if t["on"] == "schedule": + text = schedule.describe(t["cron"]) + else: + text = f"once, on {timers.local(st['at'], tz, now)}" if st.get("at") else "once" + note = { + "done": "Its time has come and gone; give it a new time to run again.", + "missed": "Lens was off when it was due.", + "failed": "It couldn't be set; save the automation again.", + }.get(st["status"]) + out.append( + { + "id": f"automation:{a['id']}:{alias}", + "kind": "automation", + "name": a["name"], + "trigger": alias, + "on": t["on"], + "cron": t.get("cron"), + "at": t.get("at"), + "timezone": tz, + "text": text, + "enabled": bool(a.get("enabled")), + "state": st["status"], + "next_run_at": st["at"] if st["status"] == "waiting" else None, + "last_run_at": last_at, + "last_status": last_status, + "running": False, + "href": f"/automations/{a['id']}", + "namespace_names": a.get("namespace_names"), + "note": note, + } + ) + return out + + +def backup_row(db, cfg): + """The scheduled backup (Settings → Backups) as a schedule: off while backups.schedule is empty.""" + b = (cfg or {}).get("backups") or {} + st = backups.schedule_state(db) + cron = b.get("schedule") or None + nxt = (st.get("at") if st.get("plan") == backups.plan(cfg) else backups.next_at(cfg)) if cron else None + return { + "id": "backups", + "kind": "backups", + "name": "Back up the database", + "trigger": None, + "on": "schedule" if cron else "manual", + "cron": cron, + "at": None, + "timezone": b.get("timezone") or "UTC", + "text": schedule.describe(cron) if cron else "not scheduled", + "enabled": bool(cron), + "state": "on" if cron else "off", + "next_run_at": nxt, + "last_run_at": st.get("last_at"), + "last_status": ("failed" if st.get("last_error") else "done") if st.get("last_at") else None, + "running": False, + "href": "/settings/backups", + "namespace_names": None, + "note": st.get("last_error") or (None if cron else f"Keeps the newest {b.get('keep') or 7} once it has a schedule."), + } + + +def _order(row): + """Soonest first; then what has no next time (off, by hand, done), by kind and name.""" + return (row["next_run_at"] is None, row["next_run_at"] or "", KINDS.index(row["kind"]), row["name"].lower(), row["id"]) + + +def listing(db, cfg, admin=False, editable=None, now=None): + """Every schedule someone may manage: admins every routine, the scheduled backup and every automation's clock + triggers; anyone else the clock triggers of the automations they manage (those in namespaces they edit).""" + rows = [] + if admin: + rows += [routine_row(r) for r in routines.list_routines(db)] + rows.append(backup_row(db, cfg)) + for a in automations.list_automations(db, None if admin else sorted(editable or [])): + rows += automation_rows(db, a, now) + return sorted(rows, key=_order) + + +def one(db, cfg, sid, admin=False, editable=None, now=None): + """One schedule by its id, if this person manages it; KeyError otherwise (so ids don't leak).""" + kind, xid, alias = parse_id(sid) + if kind in ("routine", "backups") and not admin: + raise KeyError(sid) + if kind == "routine": + return routine_row(routines.get(db, xid)) + if kind == "backups": + return backup_row(db, cfg) + a = automations.get(db, xid) + if not automations.manages(a, editable or [], admin): + raise KeyError(sid) + got = next((r for r in automation_rows(db, a, now) if r["trigger"] == alias), None) + if got is None: + raise KeyError(sid) + return got + + +# ---------- changing one ---------- +def retimed(a, alias, cron=None, at=None, timezone=None): + """An automation's triggers with one schedule or at trigger moved: a new cron (schedule) or time (at), and/or time + zone. The rest are kept as they are; automations.update checks the result.""" + out, found = [], False + for t in a.get("triggers") or []: + t = dict(t) + if t.get("as") == alias and t.get("on") in CLOCK: + found = True + if cron is not None: + if t["on"] != "schedule": + raise ValueError(f"trigger {alias} runs once at a time: change its time (at), not a cron") + t["cron"] = cron + if at is not None: + if t["on"] != "at": + raise ValueError(f"trigger {alias} repeats: change its schedule (cron), not a time") + t["at"] = at + if timezone is not None: + t["timezone"] = timezone + out.append(t) + if not found: + raise KeyError(alias) + return out + + +def run_automation(db, cfg, aid, alias, by=None, over_budget=False, now=None): + """Run an automation now as its clock trigger `alias` would: on the clock.tick its time makes, here and now. + Limits and budgets apply as to any run. {run, status, why}.""" + a = automations.get(db, aid) + t = next((x for x in a["triggers"] if x["as"] == alias and x.get("on") in CLOCK), None) + if t is None: + raise KeyError(alias) + when = now or dt.datetime.now(dt.timezone.utc) + tick = timers.tick(aid, alias, when, t.get("timezone") or "UTC", t.get("cron"), a.get("spaces")) + got = automations.run(db, cfg, aid, alias, tick, by=by, over_budget=over_budget) + return {"run": got["run"], "status": got["status"], "why": got["why"]} + + +def backup_settings(given, had=None): + """The backups settings a change ({cron, timezone, enabled}, as given) makes: switched off, or with no cron, there + is no schedule; switched on, it needs one. settings.save checks the values.""" + out = {} + if given.get("enabled") is False or ("cron" in given and not given["cron"]): + out["schedule"] = None + elif given.get("cron"): + out["schedule"] = given["cron"] + elif given.get("enabled") and not had: + raise ValueError("give the backup a schedule (cron), like 0 3 * * * for every night at 03:00, to switch it on") + if given.get("timezone") is not None: + out["timezone"] = given["timezone"] or "UTC" + return out diff --git a/fastapi_backend/app/schemas/schedules.py b/fastapi_backend/app/schemas/schedules.py new file mode 100644 index 000000000..89fedaaed --- /dev/null +++ b/fastapi_backend/app/schemas/schedules.py @@ -0,0 +1,67 @@ +"""Schedules (docs/schedules.md): everything that runs on a clock, in one list: routines, automations' schedule and at +triggers, and the scheduled backup.""" + +from __future__ import annotations + +from typing import Literal + +from pydantic import Field + +from app.schemas.common import RequestModel, ResponseModel + + +class Schedule(ResponseModel): + id: str = Field(description="routine:, automation:: or backups") + kind: Literal["routine", "automation", "backups"] + name: str = Field(description="the routine's or automation's name") + trigger: str | None = Field(None, description="an automation's trigger (its `as`)") + on: Literal["schedule", "at", "manual"] = Field( + description="schedule: repeats on a cron; at: once, at a time; manual: no schedule (a routine run by hand, no backups)" + ) + cron: str | None = Field(None, description="five-field cron (minute hour day month weekday) or @daily...") + at: str | None = Field(None, description="an at trigger's time (ISO 8601, in its time zone when it names none)") + timezone: str = "UTC" + text: str = Field(description="when it runs, in words: every weekday at 07:00, once on Fri 16 Oct at 07:00, ...") + enabled: bool = Field(description="whether it runs on its own (for an automation: the whole automation is on)") + state: str = Field( + description="on, off or running (routines, the backup); waiting, done (an at trigger whose time came), missed, " + "failed or off (automations)" + ) + next_run_at: str | None = Field(None, description="when it runs next (UTC); none while it's off or has no schedule") + last_run_at: str | None = None + last_status: str | None = Field(None, description="how its last run went (done, error, failed, partly, skipped, ...)") + running: bool = False + href: str = Field(description="its page in the web app") + namespace_names: list[str | None] | None = Field(None, description="the namespaces it works in; none for every one") + note: str | None = Field(None, description="something to know about it: why it doesn't run, its last error") + + +class ScheduleCatalog(ResponseModel): + schedules: list[Schedule] + + +class ScheduleChange(RequestModel): + cron: str | None = Field( + None, + description="a new schedule (five-field cron or @daily...); null for a routine runs it only by hand, and for the " + "backup stops scheduled backups", + ) + at: str | None = Field(None, description="a new time for an automation's at trigger, like 2026-11-02T07:30") + timezone: str | None = Field(None, description="a time zone, like Europe/London") + enabled: bool | None = Field( + None, description="switch it on or off: an automation's whole automation; the backup off clears its schedule" + ) + + +class ScheduleRun(RequestModel): + over_budget: bool = Field(False, description="run it even though it's over a budget (docs/budgets.md)") + + +class ScheduleStarted(ResponseModel): + status: str = Field( + description="asked (a routine starts within half a minute), done, waiting, partly, failed, held (over a budget), " + "skipped (its If was false), limited or off (automations), or done for a backup" + ) + why: str | None = Field(None, description="why it didn't run, or was held") + run: int | None = Field(None, description="an automation's run (GET /api/v1/automations/runs/{run})") + backup: str | None = Field(None, description="the backup it took") diff --git a/fastapi_backend/tests/api/test_mcp.py b/fastapi_backend/tests/api/test_mcp.py index 27ec14753..c44cf7a95 100644 --- a/fastapi_backend/tests/api/test_mcp.py +++ b/fastapi_backend/tests/api/test_mcp.py @@ -97,6 +97,8 @@ def test_clients_are_sent_to_sign_in(client, app, env): "set_automation_vars", "save_automation", "run_automation", + "set_schedule", + "run_schedule", ] assert next(t for t in tools if t["name"] == "search")["inputSchema"]["required"] == ["query"] # API tokens and sessions work too diff --git a/fastapi_backend/tests/api/test_schedules.py b/fastapi_backend/tests/api/test_schedules.py new file mode 100644 index 000000000..d5bf6dcdd --- /dev/null +++ b/fastapi_backend/tests/api/test_schedules.py @@ -0,0 +1,164 @@ +"""Schedules (docs/schedules.md): everything that runs on a clock in one list, like a crontab (routines, automations' +schedule and at triggers, the scheduled backup), each changed, switched and run from there through its own checks; and +the same for agents over MCP.""" + +from __future__ import annotations + +import datetime as dt + +from app.domain import routines, store, timers +from tests.api.test_automation_tools import tool, tool_error +from tests.helpers import login, make_user + +SAY = { + "nodes": [ + {"id": "i", "type": "input"}, + {"id": "a", "type": "action", "config": {"action": "log_line", "params": {"text": "It is {{ event.object.local }}"}}}, + ], + "edges": [{"source": "i", "target": "a"}], +} + + +def _env(client, new_client, db): + make_user(db, "root@x.io", "root password 1", admin=True) + make_user(db, "ed@x.io", "editor password 1", roles={"pods": "editor"}) + make_user(db, "vi@x.io", "viewer password 1", roles={"pods": "viewer"}) + db.q("UPDATE routine SET enabled = false") # the routines Lens starts with aren't what these are about + h = login(client, "root@x.io", "root password 1") + he = login(new_client(), "ed@x.io", "editor password 1") + hv = login(new_client(), "vi@x.io", "viewer password 1") + pods = store.ns_id(db, "pods") + r = client.post("/api/v1/routines", headers=h, json={"name": "Sync nightly", "schedule": "0 3 * * *", "actions": [{"type": "sync"}]}) + assert r.status_code == 200, r.text + soon = (dt.datetime.now(dt.UTC) + dt.timedelta(days=2)).strftime("%Y-%m-%dT%H:%M") + triggers = [ + {"as": "morning", "on": "schedule", "cron": "0 7 * * *", "timezone": "Europe/London"}, + {"as": "once", "on": "at", "at": soon, "timezone": "UTC"}, + {"as": "new", "on": "event", "kinds": ["asset.added"]}, + ] + a = client.post("/api/v1/automations", headers=he, json={"name": "Mornings", "triggers": triggers, "graph": SAY, "spaces": [pods]}) + assert a.status_code == 200, a.text + return {"h": h, "he": he, "hv": hv, "routine": r.json()["id"], "auto": a.json()["id"], "soon": soon} + + +def _ids(client, h): + r = client.get("/api/v1/schedules", headers=h) + assert r.status_code == 200, r.text + return {s["id"]: s for s in r.json()["schedules"]} + + +def test_one_list_holds_every_routine_automation_schedule_and_the_backup(client, new_client, db): + env = _env(client, new_client, db) + rid, aid = env["routine"], env["auto"] + got = _ids(client, env["h"]) + # admins: every routine (those switched off and run by hand too), each clock trigger of every automation, the backup + assert {f"routine:{rid}", f"automation:{aid}:morning", f"automation:{aid}:once", "backups"} <= set(got) + assert f"automation:{aid}:new" not in got # what happens isn't a clock + assert len([s for s in got if s.startswith("routine:")]) == len(routines.list_routines(db)) + r = got[f"routine:{rid}"] + assert (r["kind"], r["text"], r["cron"], r["enabled"], r["state"], r["href"]) == ( + "routine", + "every day at 03:00", + "0 3 * * *", + True, + "on", + f"/routines/{rid}", + ) + m = got[f"automation:{aid}:morning"] + assert m["text"] == "every day at 07:00" and m["timezone"] == "Europe/London" and m["state"] == "waiting" + assert m["next_run_at"] == timers.get(db, f"sched-{aid}-morning")["at"] and m["namespace_names"] == ["pods"] + once = got[f"automation:{aid}:once"] + assert once["on"] == "at" and once["text"].startswith("once, on ") and once["next_run_at"] + b = got["backups"] + assert (b["enabled"], b["text"], b["next_run_at"], b["href"]) == (False, "not scheduled", None, "/settings/backups") + # soonest first; what has no next time after + order = [s["next_run_at"] for s in client.get("/api/v1/schedules", headers=env["h"]).json()["schedules"]] + times = [t for t in order if t] + assert times == sorted(times) and order[: len(times)] == times + # anyone else: the clock triggers of the automations they manage, and nothing of the admins' + mine = _ids(client, env["he"]) + assert set(mine) == {f"automation:{aid}:morning", f"automation:{aid}:once"} + assert client.get(f"/api/v1/schedules/routine:{rid}", headers=env["he"]).status_code == 404 + assert client.get("/api/v1/schedules/backups", headers=env["he"]).status_code == 404 + assert _ids(client, env["hv"]) == {} # a viewer manages no automation + assert client.get(f"/api/v1/schedules/automation:{aid}:morning", headers=env["hv"]).status_code == 404 + assert client.get("/api/v1/schedules/nonsense", headers=env["h"]).status_code == 404 + + +def test_schedules_are_changed_switched_and_run_from_the_list(client, new_client, db): + env = _env(client, new_client, db) + rid, aid, h, he = env["routine"], env["auto"], env["h"], env["he"] + + def patch(sid, hh, **body): + return client.patch(f"/api/v1/schedules/{sid}", headers=hh, json=body) + + # a routine: a new time, then only by hand, then off + r = patch(f"routine:{rid}", h, cron="30 2 * * 1-5", timezone="Europe/Stockholm") + assert r.status_code == 200, r.text + assert r.json()["text"] == "every weekday at 02:30" and r.json()["timezone"] == "Europe/Stockholm" and r.json()["next_run_at"] + assert routines.get(db, rid)["schedule"] == "30 2 * * 1-5" + assert "five fields" in patch(f"routine:{rid}", h, cron="daily").json()["detail"] + got = patch(f"routine:{rid}", h, cron=None).json() + assert (got["on"], got["text"], got["next_run_at"]) == ("manual", "only when run by hand", None) + assert patch(f"routine:{rid}", h, enabled=False).json()["state"] == "off" + assert patch(f"routine:{rid}", he, enabled=True).status_code == 404 # routines are the admins' + assert patch(f"routine:{rid}", h).status_code == 400 + # run now, even when off: it starts when the scheduler next looks + r = client.post(f"/api/v1/schedules/routine:{rid}/run", headers=h) + assert r.status_code == 200 and r.json()["status"] == "asked" and routines.get(db, rid)["run_now"] + + # an automation's schedule: moved, through the automation's own checks; its timer follows + m = f"automation:{aid}:morning" + got = patch(m, he, cron="30 6 * * 1-5").json() + assert got["text"] == "every weekday at 06:30" and got["timezone"] == "Europe/London" + assert timers.get(db, f"sched-{aid}-morning")["payload"]["cron"] == "30 6 * * 1-5" + assert got["next_run_at"] == timers.get(db, f"sched-{aid}-morning")["at"] + assert "never runs" in patch(m, he, cron="0 0 31 feb *").json()["detail"] + assert "repeats" in patch(m, he, at="2030-01-01T07:00").json()["detail"] + later = (dt.datetime.now(dt.UTC) + dt.timedelta(days=5)).strftime("%Y-%m-%dT%H:%M") + once = patch(f"automation:{aid}:once", he, at=later).json() + assert once["at"].startswith(later) and once["next_run_at"].startswith(later) + assert patch(m, env["hv"], enabled=False).status_code == 404 # a viewer doesn't manage it + # switched off: the whole automation, and its timers are called off + off = patch(m, he, enabled=False).json() + assert (off["enabled"], off["state"], off["next_run_at"]) == (False, "off", None) + assert timers.get(db, f"sched-{aid}-morning")["status"] == "cancelled" + # run now: here, as the schedule would when its time comes + r = client.post(f"/api/v1/schedules/{m}/run", headers=he) + assert r.status_code == 200, r.text + ran = r.json() + assert ran["status"] == "done" and ran["run"] + run = client.get(f"/api/v1/automations/runs/{ran['run']}", headers=he).json() + assert run["trigger"] == "morning" and run["intents"][0]["result"]["line"].startswith("It is ") + assert _ids(client, he)[m]["last_status"] == "done" + assert patch(m, he, enabled=True).json()["state"] == "waiting" + + # the backup: given a schedule it's on; switched off it has none; on again needs one + got = patch("backups", h, cron="0 4 * * *", timezone="Europe/London").json() + assert (got["enabled"], got["text"], got["timezone"]) == (True, "every day at 04:00", "Europe/London") and got["next_run_at"] + assert patch("backups", h, enabled=False).json()["enabled"] is False + assert "give the backup a schedule" in patch("backups", h, enabled=True).json()["detail"] + assert "backups.schedule" in patch("backups", h, cron="nope").json()["detail"] + assert patch("backups", he, cron="0 4 * * *").status_code == 404 + # taken now through Settings → Backups' own route (an in-memory database has nothing to copy) + r = client.post("/api/v1/schedules/backups/run", headers=h) + assert r.status_code in (200, 400) and ("in-memory" in r.text or r.json()["backup"]) + + +def test_agents_list_change_and_run_schedules_over_mcp(client, new_client, db): + env = _env(client, new_client, db) + aid, he = env["auto"], env["he"] + m = f"automation:{aid}:morning" + got = tool(client, he, "schedules")["schedules"] + assert [s["id"] for s in got] == [f"automation:{aid}:once", m] or [s["id"] for s in got] == [m, f"automation:{aid}:once"] + assert tool(client, env["h"], "schedules", kind="backups")["schedules"][0]["id"] == "backups" + changed = tool(client, he, "set_schedule", schedule_id=m, cron="0 8 * * 1-5", timezone="UTC") + assert changed["text"] == "every weekday at 08:00" and changed["timezone"] == "UTC" + assert "say what changes" in tool_error(client, he, "set_schedule", schedule_id=m) + assert "switch it off instead" in tool_error(client, he, "set_schedule", schedule_id=m, by_hand=True) + assert "not found" in tool_error(client, he, "set_schedule", schedule_id=f"routine:{env['routine']}", enabled=False) + by_hand = tool(client, env["h"], "set_schedule", schedule_id=f"routine:{env['routine']}", by_hand=True) + assert by_hand["on"] == "manual" + ran = tool(client, he, "run_schedule", schedule_id=m) + assert ran["status"] == "done" and ran["run"] + assert "not found" in tool_error(client, env["hv"], "run_schedule", schedule_id=m) diff --git a/mkdocs.yml b/mkdocs.yml index 0f43c58e3..554ace12f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -89,6 +89,7 @@ nav: - NSFW classification: nsfw.md - Notifications: notifications.md - Automations: automations.md + - Schedules: schedules.md - Timeline: timeline.md - Knowledge: - Graph and Cypher: graph.md diff --git a/nextjs-frontend/__tests__/navigation.test.ts b/nextjs-frontend/__tests__/navigation.test.ts index a40420f08..f194dfa55 100644 --- a/nextjs-frontend/__tests__/navigation.test.ts +++ b/nextjs-frontend/__tests__/navigation.test.ts @@ -33,6 +33,14 @@ describe("navigation", () => { ).toEqual(["Costs", "Analytics", "Settings", "Admin"]); }); + it("has Schedules, everything that runs on a clock, under Automate for everyone", () => { + for (const admin of [true, false]) { + expect(navFor(admin).find((i) => i.href === "/schedules")?.group).toBe("Automate"); + } + expect(isActive("/schedules", "/schedules")).toBe(true); + expect(isActive("/schedules", "/routines")).toBe(false); + }); + it("matches the active section", () => { expect(isActive("/", "/")).toBe(true); expect(isActive("/library", "/")).toBe(false); diff --git a/nextjs-frontend/__tests__/schedules-model.test.ts b/nextjs-frontend/__tests__/schedules-model.test.ts new file mode 100644 index 000000000..aeea58c42 --- /dev/null +++ b/nextjs-frontend/__tests__/schedules-model.test.ts @@ -0,0 +1,105 @@ +import type { Schedule } from "@/app/openapi-client/types.gen"; +import { + changesOf, + counts, + draftOf, + filtered, + lastOf, + noNext, + presetsFor, + whatText, +} from "@/components/schedules/model"; + +function row(over: Partial = {}): Schedule { + return { + id: "routine:3", + kind: "routine", + name: "Sync nightly", + on: "schedule", + cron: "0 3 * * *", + timezone: "UTC", + text: "every day at 03:00", + enabled: true, + state: "on", + next_run_at: "2026-10-18T03:00:00+00:00", + href: "/routines/3", + namespace_names: null, + ...over, + }; +} + +const morning = row({ + id: "automation:4:morning", + kind: "automation", + name: "Mornings", + trigger: "morning", + cron: "0 7 * * 1-5", + timezone: "Europe/London", + text: "every weekday at 07:00", + state: "waiting", + href: "/automations/4", + namespace_names: ["pods"], +}); +const once = row({ + id: "automation:4:once", + kind: "automation", + name: "Mornings", + trigger: "once", + on: "at", + cron: null, + at: "2026-11-02T07:30:00", + text: "once, on Mon 2 Nov at 07:30", + state: "waiting", + namespace_names: ["pods"], +}); +const backup = row({ + id: "backups", + kind: "backups", + name: "Back up the database", + on: "manual", + cron: null, + enabled: false, +}); + +test("filters by kind and counts each, keeping the server's order", () => { + const rows = [morning, row(), backup, once]; + expect(counts(rows)).toEqual({ all: 4, routine: 1, automation: 2, backups: 1 }); + expect(filtered(rows, "automation").map((r) => r.id)).toEqual(["automation:4:morning", "automation:4:once"]); + expect(filtered(rows, "all")).toBe(rows); +}); + +test("says what each row is, with its trigger and namespaces", () => { + expect(whatText(row())).toBe("Routine · every namespace"); + expect(whatText(morning)).toBe("Automation · morning · pods"); + expect(whatText(backup)).toBe("Backup"); +}); + +test("labels last runs and why there's no next one", () => { + expect(lastOf("done")).toEqual({ label: "Done", tone: "green" }); + expect(lastOf("error").tone).toBe("red"); + expect(lastOf(null).label).toBe("—"); + expect(noNext(row({ enabled: false }))).toBeNull(); + expect(noNext(row({ on: "manual", cron: null }))).toBe("Only by hand"); + expect(noNext(row({ ...backup, enabled: true }))).toBe("No schedule"); + expect(noNext({ ...once, state: "done" })).toBe("Its time has passed"); + expect(noNext({ ...once, state: "missed" })).toBe("Missed while Lens was off"); + expect(noNext(row({ running: true }))).toBe("Running now"); +}); + +test("offers by hand to routines, no schedule to the backup, and neither to automations", () => { + expect(presetsFor(row()).map((p) => p.value)).toContain("manual"); + expect(presetsFor(morning).map((p) => p.value)).not.toContain("manual"); + expect(presetsFor(backup).find((p) => p.value === "manual")?.label).toBe("No scheduled backups"); +}); + +test("sends only what changed: a cron, by hand, an at trigger's time, the time zone", () => { + const d = draftOf(row()); + expect(d).toEqual({ preset: "daily", custom: "0 3 * * *", at: "", timezone: "UTC" }); + expect(changesOf(row(), d)).toBeNull(); + expect(changesOf(row(), { ...d, preset: "weekdays" })).toEqual({ cron: "0 9 * * 1-5" }); + expect(changesOf(row(), { ...d, preset: "manual" })).toEqual({ cron: null }); + expect(changesOf(row(), { ...d, preset: "custom", custom: " 30 2 * * 1-5 " })).toEqual({ cron: "30 2 * * 1-5" }); + expect(changesOf(morning, { ...draftOf(morning), timezone: "UTC" })).toEqual({ timezone: "UTC" }); + expect(draftOf(once).at).toBe("2026-11-02T07:30"); + expect(changesOf(once, { ...draftOf(once), at: "2026-11-03T08:00" })).toEqual({ at: "2026-11-03T08:00" }); +}); diff --git a/nextjs-frontend/__tests__/schedules-page.test.tsx b/nextjs-frontend/__tests__/schedules-page.test.tsx new file mode 100644 index 000000000..f0e47b668 --- /dev/null +++ b/nextjs-frontend/__tests__/schedules-page.test.tsx @@ -0,0 +1,165 @@ +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { fireEvent, render, screen, waitFor, within } from "@testing-library/react"; +import "@testing-library/jest-dom"; +import type { ReactNode } from "react"; + +import { Routines, Schedules } from "@/app/openapi-client"; +import type { Schedule } from "@/app/openapi-client/types.gen"; +import { SchedulesPage } from "@/components/schedules/schedules-page"; +import { ToastProvider } from "@/components/ui/toast"; +import { TooltipProvider } from "@/components/ui/tooltip"; + +jest.mock("@/app/openapi-client", () => ({ + Schedules: { listSchedules: jest.fn(), changeSchedule: jest.fn(), runSchedule: jest.fn() }, + Routines: { previewSchedule: jest.fn() }, +})); +jest.mock("next-auth/react", () => ({ useSession: () => ({ data: { accessToken: "t" } }) })); +let admin = true; +jest.mock("@/lib/hooks/session", () => ({ useArchive: () => ({ admin, me: { email: "root@x.io" } }) })); + +const ok = (data: unknown) => Promise.resolve({ data, response: { ok: true, status: 200 } }); +const m = (f: unknown) => f as jest.Mock; + +function row(over: Partial): Schedule { + return { + id: "routine:3", + kind: "routine", + name: "Sync nightly", + on: "schedule", + cron: "0 3 * * *", + timezone: "UTC", + text: "every day at 03:00", + enabled: true, + state: "on", + next_run_at: new Date(Date.now() + 3_600_000).toISOString(), + last_run_at: new Date(Date.now() - 3_600_000).toISOString(), + last_status: "done", + href: "/routines/3", + namespace_names: null, + ...over, + }; +} + +let rows: Schedule[] = []; +beforeEach(() => { + admin = true; + rows = [ + row({}), + row({ + id: "automation:4:morning", + kind: "automation", + name: "Mornings", + trigger: "morning", + cron: "0 7 * * 1-5", + timezone: "Europe/London", + text: "every weekday at 07:00", + state: "waiting", + href: "/automations/4", + namespace_names: ["pods"], + }), + row({ + id: "backups", + kind: "backups", + name: "Back up the database", + on: "manual", + cron: null, + text: "not scheduled", + enabled: false, + state: "off", + next_run_at: null, + last_run_at: null, + last_status: null, + href: "/settings/backups", + }), + ]; + m(Schedules.listSchedules).mockImplementation(() => ok({ schedules: rows })); + m(Schedules.changeSchedule).mockImplementation( + ({ path, body }: { path: { sid: string }; body: Partial }) => { + const r = rows.find((x) => x.id === path.sid)!; + const text = body.cron === "0 9 * * 1-5" ? "every weekday at 09:00" : r.text; + return ok({ ...r, ...body, text }); + }, + ); + m(Schedules.runSchedule).mockImplementation(({ path }: { path: { sid: string } }) => + ok(path.sid.startsWith("routine") ? { status: "asked" } : { status: "done", run: 51 }), + ); + m(Routines.previewSchedule).mockImplementation(({ query }: { query: { schedule: string; timezone: string } }) => + ok({ schedule: query.schedule, timezone: query.timezone, text: "every weekday at 09:00", next: [] }), + ); +}); + +function wrap(ui: ReactNode) { + const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } }); + return render( + + + {ui} + + , + ); +} + +test("lists every routine, automation schedule and the backup, each linking to its own page", async () => { + wrap(); + const table = await screen.findByRole("table", { name: "Schedules" }); + expect(within(table).getByRole("link", { name: "Sync nightly" })).toHaveAttribute("href", "/routines/3"); + expect(within(table).getByRole("link", { name: "Mornings" })).toHaveAttribute("href", "/automations/4"); + expect(within(table).getByRole("link", { name: "Back up the database" })).toHaveAttribute( + "href", + "/settings/backups", + ); + expect(within(table).getByText("every weekday at 07:00")).toBeInTheDocument(); + expect(within(table).getByText("Automation · morning · pods")).toBeInTheDocument(); + expect(within(table).getByText("not scheduled")).toBeInTheDocument(); + // a filter per kind, with counts + fireEvent.click(screen.getByRole("radio", { name: /Automations/ })); + expect(within(table).queryByRole("link", { name: "Sync nightly" })).not.toBeInTheDocument(); + expect(within(table).getByRole("link", { name: "Mornings" })).toBeInTheDocument(); +}); + +test("switches one off, runs one now and changes when one runs, from the list", async () => { + wrap(); + await screen.findByRole("table", { name: "Schedules" }); + fireEvent.click(screen.getByRole("switch", { name: "Mornings (morning) on" })); + await waitFor(() => + expect(Schedules.changeSchedule).toHaveBeenCalledWith( + expect.objectContaining({ path: { sid: "automation:4:morning" }, body: { enabled: false } }), + ), + ); + fireEvent.click(screen.getByRole("button", { name: "Run Sync nightly now" })); + await waitFor(() => + expect(Schedules.runSchedule).toHaveBeenCalledWith(expect.objectContaining({ path: { sid: "routine:3" } })), + ); + expect(await screen.findByText("Sync nightly starts within half a minute.")).toBeInTheDocument(); + // change it: a custom cron, starting from the one it has, saved with Enter + fireEvent.click(screen.getByRole("button", { name: "Change when Sync nightly runs" })); + const dialog = await screen.findByRole("dialog"); + fireEvent.change(within(dialog).getByLabelText("Schedule"), { target: { value: "custom" } }); + const cron = within(dialog).getByLabelText("Cron"); + expect(cron).toHaveValue("0 3 * * *"); + fireEvent.change(cron, { target: { value: "0 9 * * 1-5" } }); + fireEvent.keyDown(cron, { key: "Enter" }); + await waitFor(() => + expect(Schedules.changeSchedule).toHaveBeenCalledWith( + expect.objectContaining({ path: { sid: "routine:3" }, body: { cron: "0 9 * * 1-5" } }), + ), + ); + expect(await screen.findByText("Sync nightly: every weekday at 09:00.")).toBeInTheDocument(); +}); + +test("switching the backup on asks for its schedule first", async () => { + wrap(); + await screen.findByRole("table", { name: "Schedules" }); + fireEvent.click(screen.getByRole("switch", { name: "Back up the database on" })); + expect(await screen.findByRole("dialog", { name: "When Back up the database runs" })).toBeInTheDocument(); + expect(Schedules.changeSchedule).not.toHaveBeenCalled(); +}); + +test("someone who isn't an admin sees their automations' schedules and no filter", async () => { + admin = false; + rows = rows.filter((r) => r.kind === "automation"); + wrap(); + await screen.findByRole("table", { name: "Schedules" }); + expect(screen.getByText(/your automations/)).toBeInTheDocument(); + expect(screen.queryByRole("radiogroup", { name: "Show" })).not.toBeInTheDocument(); +}); diff --git a/nextjs-frontend/app/(app)/schedules/page.tsx b/nextjs-frontend/app/(app)/schedules/page.tsx new file mode 100644 index 000000000..a754296a8 --- /dev/null +++ b/nextjs-frontend/app/(app)/schedules/page.tsx @@ -0,0 +1,11 @@ +import type { Metadata } from "next"; + +import { SchedulesPage } from "@/components/schedules/schedules-page"; + +export const metadata: Metadata = { title: "Schedules" }; + +/** Everything that runs on a clock, like a crontab: routines, automations' schedules and the backup (backend: + * GET /api/v1/schedules, docs/schedules.md). */ +export default function Page() { + return ; +} diff --git a/nextjs-frontend/app/openapi-client/index.ts b/nextjs-frontend/app/openapi-client/index.ts index 43c7de15e..76bd56919 100644 --- a/nextjs-frontend/app/openapi-client/index.ts +++ b/nextjs-frontend/app/openapi-client/index.ts @@ -38,6 +38,7 @@ export { Rdf, Resources, Routines, + Schedules, Search, Searches, Sensors, @@ -303,6 +304,11 @@ export type { ChangePasswordErrors, ChangePasswordResponse, ChangePasswordResponses, + ChangeScheduleData, + ChangeScheduleError, + ChangeScheduleErrors, + ChangeScheduleResponse, + ChangeScheduleResponses, Chat, ChatCapabilities, ChatCapabilitiesData, @@ -1421,6 +1427,11 @@ export type { GetSandboxGatewayData, GetSandboxGatewayResponse, GetSandboxGatewayResponses, + GetScheduleData, + GetScheduleError, + GetScheduleErrors, + GetScheduleResponse, + GetScheduleResponses, GetSensorData, GetSensorError, GetSensorErrors, @@ -2021,6 +2032,9 @@ export type { ListRunsErrors, ListRunsResponse, ListRunsResponses, + ListSchedulesData, + ListSchedulesResponse, + ListSchedulesResponses, ListSearchesData, ListSearchesResponse, ListSearchesResponses, @@ -2885,6 +2899,11 @@ export type { RunsCausedErrors, RunsCausedResponse, RunsCausedResponses, + RunScheduleData, + RunScheduleError, + RunScheduleErrors, + RunScheduleResponse, + RunScheduleResponses, RunWorkflowData, RunWorkflowError, RunWorkflowErrors, @@ -2959,7 +2978,12 @@ export type { ScanWatchErrors, ScanWatchResponse, ScanWatchResponses, + Schedule, + ScheduleCatalog, + ScheduleChange, SchedulePreview, + ScheduleRun, + ScheduleStarted, SealVaultData, SealVaultError, SealVaultErrors, diff --git a/nextjs-frontend/app/openapi-client/sdk.gen.ts b/nextjs-frontend/app/openapi-client/sdk.gen.ts index a8a1ba2f7..57a02d8f0 100644 --- a/nextjs-frontend/app/openapi-client/sdk.gen.ts +++ b/nextjs-frontend/app/openapi-client/sdk.gen.ts @@ -100,6 +100,9 @@ import type { ChangePasswordData, ChangePasswordErrors, ChangePasswordResponses, + ChangeScheduleData, + ChangeScheduleErrors, + ChangeScheduleResponses, ChatCapabilitiesData, ChatCapabilitiesResponses, ChatToolsData, @@ -691,6 +694,9 @@ import type { GetRunResponses, GetSandboxGatewayData, GetSandboxGatewayResponses, + GetScheduleData, + GetScheduleErrors, + GetScheduleResponses, GetSensorData, GetSensorErrors, GetSensorResponses, @@ -1013,6 +1019,8 @@ import type { ListRunsData, ListRunsErrors, ListRunsResponses, + ListSchedulesData, + ListSchedulesResponses, ListSearchesData, ListSearchesResponses, ListSegmentEditsData, @@ -1390,6 +1398,9 @@ import type { RunsCausedData, RunsCausedErrors, RunsCausedResponses, + RunScheduleData, + RunScheduleErrors, + RunScheduleResponses, RunWorkflowData, RunWorkflowErrors, RunWorkflowResponses, @@ -11308,6 +11319,76 @@ export class Routines { } } +export class Schedules { + /** + * List Schedules + * + * Everything that runs on a clock that you manage, soonest first: for admins every routine (those run only by + * hand too) and the scheduled backup; for everyone the schedule and at triggers of their automations. Each with + * when it runs in words, its next and last run, how that went and whether it's on. + */ + public static listSchedules( + options?: Options, + ): RequestResult { + return (options?.client ?? client).get({ + url: "/api/v1/schedules", + ...options, + }); + } + + /** + * Get Schedule + */ + public static getSchedule( + options: Options, + ): RequestResult { + return (options.client ?? client).get({ + url: "/api/v1/schedules/{sid}", + ...options, + }); + } + + /** + * Change Schedule + * + * Change when it runs or switch it on or off; give only what changes. A routine's `cron: null` runs it only by + * hand. Switching an automation's schedule switches the whole automation (every trigger it has). Switching the + * backup off clears backups.schedule; switching it on needs a cron. + */ + public static changeSchedule( + options: Options, + ): RequestResult { + return (options.client ?? client).patch({ + url: "/api/v1/schedules/{sid}", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Run Schedule + * + * Run it now, even when it's off: a routine as soon as the scheduler next looks (within half a minute), an + * automation here and now as its trigger would when its time comes, the backup now (it can take a while). A run over + * a budget is refused (routines: 409) or held for your pick (automations) unless over_budget is true. + */ + public static runSchedule( + options: Options, + ): RequestResult { + return (options.client ?? client).post({ + url: "/api/v1/schedules/{sid}/run", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } +} + export class Sensors { /** * List Sensors diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index 36a98b46d..965b7ca2d 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -18901,6 +18901,154 @@ export type SavedView = { [key: string]: unknown; }; +/** + * Schedule + */ +export type Schedule = { + /** + * Id + * + * routine:, automation:: or backups + */ + id: string; + /** + * Kind + */ + kind: "routine" | "automation" | "backups"; + /** + * Name + * + * the routine's or automation's name + */ + name: string; + /** + * Trigger + * + * an automation's trigger (its `as`) + */ + trigger?: string | null; + /** + * On + * + * schedule: repeats on a cron; at: once, at a time; manual: no schedule (a routine run by hand, no backups) + */ + on: "schedule" | "at" | "manual"; + /** + * Cron + * + * five-field cron (minute hour day month weekday) or @daily... + */ + cron?: string | null; + /** + * At + * + * an at trigger's time (ISO 8601, in its time zone when it names none) + */ + at?: string | null; + /** + * Timezone + */ + timezone?: string; + /** + * Text + * + * when it runs, in words: every weekday at 07:00, once on Fri 16 Oct at 07:00, ... + */ + text: string; + /** + * Enabled + * + * whether it runs on its own (for an automation: the whole automation is on) + */ + enabled: boolean; + /** + * State + * + * on, off or running (routines, the backup); waiting, done (an at trigger whose time came), missed, failed or off (automations) + */ + state: string; + /** + * Next Run At + * + * when it runs next (UTC); none while it's off or has no schedule + */ + next_run_at?: string | null; + /** + * Last Run At + */ + last_run_at?: string | null; + /** + * Last Status + * + * how its last run went (done, error, failed, partly, skipped, ...) + */ + last_status?: string | null; + /** + * Running + */ + running?: boolean; + /** + * Href + * + * its page in the web app + */ + href: string; + /** + * Namespace Names + * + * the namespaces it works in; none for every one + */ + namespace_names?: Array | null; + /** + * Note + * + * something to know about it: why it doesn't run, its last error + */ + note?: string | null; + [key: string]: unknown; +}; + +/** + * ScheduleCatalog + */ +export type ScheduleCatalog = { + /** + * Schedules + */ + schedules: Array; + [key: string]: unknown; +}; + +/** + * ScheduleChange + */ +export type ScheduleChange = { + /** + * Cron + * + * a new schedule (five-field cron or @daily...); null for a routine runs it only by hand, and for the backup stops scheduled backups + */ + cron?: string | null; + /** + * At + * + * a new time for an automation's at trigger, like 2026-11-02T07:30 + */ + at?: string | null; + /** + * Timezone + * + * a time zone, like Europe/London + */ + timezone?: string | null; + /** + * Enabled + * + * switch it on or off: an automation's whole automation; the backup off clears its schedule + */ + enabled?: boolean | null; +}; + /** * SchedulePreview */ @@ -18924,6 +19072,49 @@ export type SchedulePreview = { [key: string]: unknown; }; +/** + * ScheduleRun + */ +export type ScheduleRun = { + /** + * Over Budget + * + * run it even though it's over a budget (docs/budgets.md) + */ + over_budget?: boolean; +}; + +/** + * ScheduleStarted + */ +export type ScheduleStarted = { + /** + * Status + * + * asked (a routine starts within half a minute), done, waiting, partly, failed, held (over a budget), skipped (its If was false), limited or off (automations), or done for a backup + */ + status: string; + /** + * Why + * + * why it didn't run, or was held + */ + why?: string | null; + /** + * Run + * + * an automation's run (GET /api/v1/automations/runs/{run}) + */ + run?: number | null; + /** + * Backup + * + * the backup it took + */ + backup?: string | null; + [key: string]: unknown; +}; + /** * SearchCreate */ @@ -42567,6 +42758,115 @@ export type UndoGraphChangeResponses = { export type UndoGraphChangeResponse = UndoGraphChangeResponses[keyof UndoGraphChangeResponses]; +export type ListSchedulesData = { + body?: never; + path?: never; + query?: never; + url: "/api/v1/schedules"; +}; + +export type ListSchedulesResponses = { + /** + * Successful Response + */ + 200: ScheduleCatalog; +}; + +export type ListSchedulesResponse = ListSchedulesResponses[keyof ListSchedulesResponses]; + +export type GetScheduleData = { + body?: never; + path: { + /** + * Sid + */ + sid: string; + }; + query?: never; + url: "/api/v1/schedules/{sid}"; +}; + +export type GetScheduleErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type GetScheduleError = GetScheduleErrors[keyof GetScheduleErrors]; + +export type GetScheduleResponses = { + /** + * Successful Response + */ + 200: Schedule; +}; + +export type GetScheduleResponse = GetScheduleResponses[keyof GetScheduleResponses]; + +export type ChangeScheduleData = { + body: ScheduleChange; + path: { + /** + * Sid + */ + sid: string; + }; + query?: never; + url: "/api/v1/schedules/{sid}"; +}; + +export type ChangeScheduleErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type ChangeScheduleError = ChangeScheduleErrors[keyof ChangeScheduleErrors]; + +export type ChangeScheduleResponses = { + /** + * Successful Response + */ + 200: Schedule; +}; + +export type ChangeScheduleResponse = ChangeScheduleResponses[keyof ChangeScheduleResponses]; + +export type RunScheduleData = { + /** + * Body + */ + body?: ScheduleRun | null; + path: { + /** + * Sid + */ + sid: string; + }; + query?: never; + url: "/api/v1/schedules/{sid}/run"; +}; + +export type RunScheduleErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type RunScheduleError = RunScheduleErrors[keyof RunScheduleErrors]; + +export type RunScheduleResponses = { + /** + * Successful Response + */ + 200: ScheduleStarted; +}; + +export type RunScheduleResponse = RunScheduleResponses[keyof RunScheduleResponses]; + export type ListSensorsData = { body?: never; path?: never; diff --git a/nextjs-frontend/components/app-shell/nav-config.ts b/nextjs-frontend/components/app-shell/nav-config.ts index 1d894e531..3637f7d05 100644 --- a/nextjs-frontend/components/app-shell/nav-config.ts +++ b/nextjs-frontend/components/app-shell/nav-config.ts @@ -1,4 +1,5 @@ import { + AlarmClock, Blocks, CalendarClock, ChartLine, @@ -72,6 +73,8 @@ export const NAV: NavItem[] = [ group: "Automate", }, { label: "Pipelines", href: "/pipelines", icon: Workflow, group: "Automate" }, + // everything that runs on a clock in one list: everyone has it, for the schedules of their own automations + { label: "Schedules", href: "/schedules", icon: AlarmClock, group: "Automate" }, { label: "Routines", href: "/routines", icon: CalendarClock, adminOnly: true, group: "Automate" }, { label: "Extensions", href: "/extensions", icon: Blocks, group: "Automate" }, // Admins see every source as a sensor; members see the watched folders feeding their namespaces. diff --git a/nextjs-frontend/components/routines/routine-editor.tsx b/nextjs-frontend/components/routines/routine-editor.tsx index a088aabff..9083ee293 100644 --- a/nextjs-frontend/components/routines/routine-editor.tsx +++ b/nextjs-frontend/components/routines/routine-editor.tsx @@ -1,9 +1,9 @@ "use client"; -import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; +import { useMutation, useQueryClient } from "@tanstack/react-query"; import { ArrowDown, ArrowUp, Plus, Trash2 } from "lucide-react"; import { useRouter } from "next/navigation"; -import { useEffect, useId, useMemo, useState } from "react"; +import { useState } from "react"; import { Routines } from "@/app/openapi-client"; import type { Routine, Watch } from "@/app/openapi-client/types.gen"; @@ -23,6 +23,7 @@ import { type Preset, type RoutineAction, } from "@/components/routines/routine-model"; +import { browserZone, SchedulePreview, ZoneInput } from "@/components/routines/schedule-fields"; import { Banner } from "@/components/ui/banner"; import { Button, IconButton } from "@/components/ui/button"; import { Checkbox, Field, Input, Select, Switch, Textarea } from "@/components/ui/field"; @@ -33,88 +34,6 @@ import { useToast } from "@/components/ui/toast"; import { data, useApiClient } from "@/lib/api/browser"; import { useArchive } from "@/lib/hooks/session"; -function browserZone(): string { - try { - return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC"; - } catch { - return "UTC"; - } -} - -function zones(): string[] { - try { - const f = (Intl as { supportedValuesOf?: (k: string) => string[] }).supportedValuesOf; - return f ? ["UTC", ...f("timeZone")] : ["UTC"]; - } catch { - return ["UTC"]; - } -} - -/** "Fri 3 Oct, 03:00" in the routine's time zone. */ -function when(iso: string, tz: string): string { - const o: Intl.DateTimeFormatOptions = { - weekday: "short", - day: "numeric", - month: "short", - hour: "2-digit", - minute: "2-digit", - }; - try { - return new Date(iso).toLocaleString("en-GB", { ...o, timeZone: tz }); - } catch { - return new Date(iso).toLocaleString("en-GB", o); - } -} - -function useDebounced(value: T, ms = 400): T { - const [v, setV] = useState(value); - useEffect(() => { - const t = setTimeout(() => setV(value), ms); - return () => clearTimeout(t); - }, [value, ms]); - return v; -} - -/** What the schedule means and its next five runs, from the server, as it's typed. */ -function SchedulePreview({ schedule, timezone }: { schedule: string | null; timezone: string }) { - const client = useApiClient(); - const s = useDebounced(schedule); - const tz = useDebounced(timezone); - const q = useQuery({ - queryKey: ["schedule-preview", s, tz], - queryFn: () => data(Routines.previewSchedule({ client, query: { schedule: s!, timezone: tz || "UTC" } })), - enabled: Boolean(s), - retry: false, - staleTime: 60_000, - }); - if (!schedule) return

Runs only when someone presses Run now.

; - if (q.isLoading || s !== schedule || tz !== timezone) - return

Checking the schedule…

; - if (q.error) - return ( -

- {(q.error as Error).message} -

- ); - if (!q.data) return null; - return ( -
-

Runs {q.data.text}

- {q.data.next.length ? ( -
    - {q.data.next.map((t) => ( -
  • - {when(t, q.data.timezone)} -
  • - ))} -
- ) : ( -

It never comes round.

- )} -
- ); -} - function PickSelect({ value, onChange }: { value: Pick | undefined; onChange: (v: Pick) => void }) { return ( @@ -302,7 +221,6 @@ export function RoutineEditor({ routine, onSaved }: { routine?: Routine; onSaved const { namespaces } = useArchive(); const watches = useWatches(); const workflows = useWorkflowCatalog(); - const zoneList = useId(); const creating = !routine; const [name, setName] = useState(routine?.name ?? ""); @@ -316,7 +234,6 @@ export function RoutineEditor({ routine, onSaved }: { routine?: Routine; onSaved (routine?.actions as RoutineAction[] | undefined) ?? [newAction("sync")], ); const [error, setError] = useState(null); - const allZones = useMemo(zones, []); const schedule = scheduleFor(preset, custom); const graphWorkflow = (id: number) => workflows.data?.workflows.find((w) => w.id === id)?.scope === "graph"; @@ -409,16 +326,7 @@ export function RoutineEditor({ routine, onSaved }: { routine?: Routine; onSaved {preset !== "manual" && ( - {({ id }) => ( - <> - setTimezone(e.target.value)} /> - - {allZones.map((z) => ( - - - )} + {({ id }) => } )} diff --git a/nextjs-frontend/components/routines/schedule-fields.tsx b/nextjs-frontend/components/routines/schedule-fields.tsx new file mode 100644 index 000000000..c11049dd1 --- /dev/null +++ b/nextjs-frontend/components/routines/schedule-fields.tsx @@ -0,0 +1,117 @@ +"use client"; + +import { useQuery } from "@tanstack/react-query"; +import { useEffect, useId, useMemo, useState } from "react"; + +import { Routines } from "@/app/openapi-client"; +import { Input } from "@/components/ui/field"; +import { data, useApiClient } from "@/lib/api/browser"; + +/** When things run: the time zone fields and the schedule preview shared by the routine editor and the Schedules + * page. */ +export function browserZone(): string { + try { + return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC"; + } catch { + return "UTC"; + } +} + +export function zones(): string[] { + try { + const f = (Intl as { supportedValuesOf?: (k: string) => string[] }).supportedValuesOf; + return f ? ["UTC", ...f("timeZone")] : ["UTC"]; + } catch { + return ["UTC"]; + } +} + +/** A time zone, typed or picked from every zone this browser knows. */ +export function ZoneInput({ id, value, onChange }: { id: string; value: string; onChange: (v: string) => void }) { + const list = useId(); + const all = useMemo(zones, []); + return ( + <> + onChange(e.target.value)} /> + + {all.map((z) => ( + + + ); +} + +/** "Fri 3 Oct, 03:00" in the routine's time zone. */ +function when(iso: string, tz: string): string { + const o: Intl.DateTimeFormatOptions = { + weekday: "short", + day: "numeric", + month: "short", + hour: "2-digit", + minute: "2-digit", + }; + try { + return new Date(iso).toLocaleString("en-GB", { ...o, timeZone: tz }); + } catch { + return new Date(iso).toLocaleString("en-GB", o); + } +} + +function useDebounced(value: T, ms = 400): T { + const [v, setV] = useState(value); + useEffect(() => { + const t = setTimeout(() => setV(value), ms); + return () => clearTimeout(t); + }, [value, ms]); + return v; +} + +/** What the schedule means and its next five runs, from the server, as it's typed. */ +export function SchedulePreview({ + schedule, + timezone, + none = "Runs only when someone presses Run now.", +}: { + schedule: string | null; + timezone: string; + /** What having no schedule means here. */ + none?: string; +}) { + const client = useApiClient(); + const s = useDebounced(schedule); + const tz = useDebounced(timezone); + const q = useQuery({ + queryKey: ["schedule-preview", s, tz], + queryFn: () => data(Routines.previewSchedule({ client, query: { schedule: s!, timezone: tz || "UTC" } })), + enabled: Boolean(s), + retry: false, + staleTime: 60_000, + }); + if (!schedule) return

{none}

; + if (q.isLoading || s !== schedule || tz !== timezone) + return

Checking the schedule…

; + if (q.error) + return ( +

+ {(q.error as Error).message} +

+ ); + if (!q.data) return null; + return ( +
+

Runs {q.data.text}

+ {q.data.next.length ? ( +
    + {q.data.next.map((t) => ( +
  • + {when(t, q.data.timezone)} +
  • + ))} +
+ ) : ( +

It never comes round.

+ )} +
+ ); +} diff --git a/nextjs-frontend/components/schedules/model.ts b/nextjs-frontend/components/schedules/model.ts new file mode 100644 index 000000000..abff73fd3 --- /dev/null +++ b/nextjs-frontend/components/schedules/model.ts @@ -0,0 +1,102 @@ +/** + * The Schedules page (docs/schedules.md): everything that runs on a clock in one list, like a crontab. Rows come from + * GET /api/v1/schedules; this file has what the page works out from them. + */ +import type { Schedule } from "@/app/openapi-client/types.gen"; +import type { Tone } from "@/components/ui/badge"; +import { PRESETS, presetOf, scheduleFor, type Preset } from "@/components/routines/routine-model"; + +export type Kind = Schedule["kind"]; +export type Filter = "all" | Kind; + +export const KIND_LABEL: Record = { routine: "Routine", automation: "Automation", backups: "Backup" }; + +export const FILTERS: { value: Filter; label: string }[] = [ + { value: "all", label: "All" }, + { value: "routine", label: "Routines" }, + { value: "automation", label: "Automations" }, + { value: "backups", label: "Backups" }, +]; + +/** The rows a filter shows, in the server's order (soonest first). */ +export function filtered(rows: Schedule[], f: Filter): Schedule[] { + return f === "all" ? rows : rows.filter((r) => r.kind === f); +} + +/** How many rows each filter shows; a filter with none isn't offered (All always is). */ +export function counts(rows: Schedule[]): Record { + const c: Record = { all: rows.length, routine: 0, automation: 0, backups: 0 }; + for (const r of rows) c[r.kind] += 1; + return c; +} + +/** What a row is, under its name: "Routine", "Automation · morning", with its namespaces. */ +export function whatText(r: Schedule): string { + const kind = r.trigger ? `${KIND_LABEL[r.kind]} · ${r.trigger}` : KIND_LABEL[r.kind]; + const ns = r.namespace_names; + if (r.kind === "backups") return kind; + return `${kind} · ${ns == null ? "every namespace" : ns.filter(Boolean).join(", ") || "no namespace"}`; +} + +const LAST: Record = { + done: { label: "Done", tone: "green" }, + partly: { label: "Partly done", tone: "gate" }, + error: { label: "Failed", tone: "red" }, + failed: { label: "Failed", tone: "red" }, + running: { label: "Running", tone: "intent" }, + waiting: { label: "Waiting", tone: "gate" }, + held: { label: "Waiting for you", tone: "gate" }, + released: { label: "Let through", tone: "neutral" }, + skipped: { label: "Skipped", tone: "neutral" }, + limited: { label: "Over a limit", tone: "gate" }, +}; + +/** How a last run went, as a badge. */ +export function lastOf(status: string | null | undefined): { label: string; tone: Tone } { + return LAST[status ?? ""] ?? { label: status ?? "—", tone: "neutral" }; +} + +/** Why a row has no next run, when it isn't simply switched off. */ +export function noNext(r: Schedule): string | null { + if (r.running) return "Running now"; + if (!r.enabled) return null; + if (r.state === "done") return "Its time has passed"; + if (r.state === "missed") return "Missed while Lens was off"; + if (r.state === "failed") return "Couldn’t be set"; + if (r.on === "manual") return r.kind === "backups" ? "No schedule" : "Only by hand"; + return null; +} + +/** The schedule choices a row offers: a routine may run only by hand and the backup may have no schedule; an + * automation's schedule trigger always has one. */ +export function presetsFor(r: Schedule): { value: Preset; label: string }[] { + return PRESETS.filter((p) => p.value !== "manual" || r.kind !== "automation").map((p) => + p.value === "manual" && r.kind === "backups" ? { value: p.value, label: "No scheduled backups" } : p, + ); +} + +export type Draft = { preset: Preset; custom: string; at: string; timezone: string }; + +/** The editor's starting state for a row: its preset, its cron when custom, its time (an at trigger) and zone. */ +export function draftOf(r: Schedule): Draft { + return { + preset: r.on === "at" ? "custom" : presetOf(r.cron), + custom: r.cron ?? "", + at: (r.at ?? "").slice(0, 16), + timezone: r.timezone || "UTC", + }; +} + +/** What PATCH /schedules/{id} gets from the editor: only what changed. Null when nothing did. */ +export function changesOf(r: Schedule, d: Draft): { cron?: string | null; at?: string; timezone?: string } | null { + const out: { cron?: string | null; at?: string; timezone?: string } = {}; + const tz = d.timezone.trim() || "UTC"; + if (r.on === "at") { + if (d.at && d.at !== (r.at ?? "").slice(0, 16)) out.at = d.at; + } else { + const cron = scheduleFor(d.preset, d.custom); + if (cron !== (r.cron ?? null)) out.cron = cron; + } + if (tz !== (r.timezone || "UTC")) out.timezone = tz; + return Object.keys(out).length ? out : null; +} diff --git a/nextjs-frontend/components/schedules/schedules-page.tsx b/nextjs-frontend/components/schedules/schedules-page.tsx new file mode 100644 index 000000000..7853b4759 --- /dev/null +++ b/nextjs-frontend/components/schedules/schedules-page.tsx @@ -0,0 +1,389 @@ +"use client"; + +import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; +import { AlarmClock, Pencil, Play } from "lucide-react"; +import Link from "next/link"; +import { useState } from "react"; + +import { Schedules } from "@/app/openapi-client"; +import type { Schedule } from "@/app/openapi-client/types.gen"; +import { scheduleFor, type Preset } from "@/components/routines/routine-model"; +import { SchedulePreview, ZoneInput } from "@/components/routines/schedule-fields"; +import { + FILTERS, + changesOf, + counts, + draftOf, + filtered, + lastOf, + noNext, + presetsFor, + whatText, + type Draft, + type Filter, +} from "@/components/schedules/model"; +import { Badge } from "@/components/ui/badge"; +import { Button, IconButton } from "@/components/ui/button"; +import { Dialog } from "@/components/ui/dialog"; +import { Field, Input, Select, Switch } from "@/components/ui/field"; +import { DateTime, EmptyState, SkeletonRows } from "@/components/ui/states"; +import { Table, Td, Th, THead, Tr } from "@/components/ui/table"; +import { Segmented } from "@/components/ui/tabs"; +import { useToast } from "@/components/ui/toast"; +import { ApiError, data, useApiClient } from "@/lib/api/browser"; +import { useArchive } from "@/lib/hooks/session"; + +export function useSchedules() { + const client = useApiClient(); + return useQuery({ + queryKey: ["schedules"], + queryFn: () => data(Schedules.listSchedules({ client })), + // a routine asked to run starts within half a minute; keep "Running" and the last run fresh + refetchInterval: 15_000, + }); +} + +/** What a run now did, for its toast. */ +function ranText(r: Schedule, got: { status: string; why?: string | null; backup?: string | null }): string { + if (got.status === "asked") return `${r.name} starts within half a minute.`; + if (got.backup) return `Took ${got.backup}.`; + if (got.status === "held") return `${got.why ?? "It’s over a budget"}. Decide on its automation’s page.`; + return got.why ? `${lastOf(got.status).label}: ${got.why}` : `${r.name}: ${lastOf(got.status).label.toLowerCase()}.`; +} + +/** When it runs, changed in place: presets, a cron, an at trigger's time, the time zone, and the next runs. */ +function EditSchedule({ row, onClose }: { row: Schedule; onClose: () => void }) { + const client = useApiClient(); + const qc = useQueryClient(); + const toast = useToast(); + const [d, setDraft] = useState(() => draftOf(row)); + const save = useMutation({ + mutationFn: (body: NonNullable>) => + data(Schedules.changeSchedule({ client, path: { sid: row.id }, body })), + onSuccess: (got) => { + void qc.invalidateQueries({ queryKey: ["schedules"] }); + toast({ tone: "green", title: "Schedule saved", body: `${got.name}: ${got.text}.` }); + onClose(); + }, + }); + const set = (p: Partial) => setDraft({ ...d, ...p }); + const cron = row.on === "at" ? null : scheduleFor(d.preset, d.custom); + const submit = () => { + const body = changesOf(row, d); + if (body) save.mutate(body); + else onClose(); + }; + return ( + !o && onClose()} + title={`When ${row.name} runs`} + description={ + row.kind === "automation" ? `Its ${row.trigger} trigger. Saving checks the automation again.` : undefined + } + actions={ + <> + + + + } + > +
+ {row.on === "at" ? ( + + {({ id, describedBy }) => ( + set({ at: e.target.value })} + /> + )} + + ) : ( + + {({ id }) => ( + set({ custom: e.target.value })} + /> + )} + + )} + {(row.on === "at" || d.preset !== "manual") && ( + + {({ id }) => set({ timezone })} />} + + )} + {row.on !== "at" && ( + + )} + {save.error && ( +

+ {(save.error as Error).message} +

+ )} +
+
+ ); +} + +/** The crontab: every routine, automation schedule and the backup, soonest first, each switched, changed and run here. */ +export function SchedulesPage() { + const { admin, me } = useArchive(); + const client = useApiClient(); + const qc = useQueryClient(); + const toast = useToast(); + const list = useSchedules(); + const [filter, setFilter] = useState("all"); + const [editing, setEditing] = useState(null); + const [overBudget, setOverBudget] = useState<{ row: Schedule; why: string } | null>(null); + const rows = list.data?.schedules ?? []; + const n = counts(rows); + const shown = filtered(rows, n[filter] ? filter : "all"); + const refresh = () => void qc.invalidateQueries({ queryKey: ["schedules"] }); + + const toggle = useMutation({ + mutationFn: (v: { row: Schedule; enabled: boolean }) => + data(Schedules.changeSchedule({ client, path: { sid: v.row.id }, body: { enabled: v.enabled } })), + onSuccess: (got) => { + refresh(); + void qc.invalidateQueries({ queryKey: ["routines"] }); + void qc.invalidateQueries({ queryKey: ["automations"] }); + toast({ + title: got.enabled ? "On" : "Off", + body: got.enabled ? `${got.name}: ${got.text}.` : `${got.name} won’t run on its own.`, + }); + }, + onError: (e: Error) => toast({ tone: "red", title: "Couldn’t switch it", body: e.message }), + }); + const run = useMutation({ + mutationFn: (v: { row: Schedule; overBudget?: boolean }) => + data(Schedules.runSchedule({ client, path: { sid: v.row.id }, body: { over_budget: Boolean(v.overBudget) } })), + onSuccess: (got, v) => { + setOverBudget(null); + refresh(); + const bad = ["failed", "error"].includes(got.status); + toast({ tone: bad ? "red" : "green", title: bad ? "The run failed" : "Run now", body: ranText(v.row, got) }); + }, + onError: (e: Error, v) => { + // over budget: say where it stands and let the person choose (docs/budgets.md) + if (e instanceof ApiError && e.status === 409) setOverBudget({ row: v.row, why: e.message }); + else toast({ tone: "red", title: "Couldn’t run it", body: e.message }); + }, + }); + const switchTo = (row: Schedule, on: boolean) => { + // the backup can't be on without a schedule: choosing one switches it on + if (on && row.kind === "backups" && !row.cron) setEditing(row); + else toggle.mutate({ row, enabled: on }); + }; + + return ( +
+
+

Schedules

+

+ Everything that runs on a clock, in one place:{" "} + {admin ? "routines, your automations and backups" : "your automations"}. +

+
+ {list.isLoading || !me ? ( + + ) : list.error ? ( + } + title="Couldn’t load schedules" + actions={} + > + {(list.error as Error).message} + + ) : !rows.length ? ( + } + title="Nothing runs on a clock yet" + actions={ + <> + {admin && ( + + )} + + + } + > + A routine or an automation with a schedule shows here, with when it runs next, how it last went and a switch. + + ) : ( + <> + {Object.values(n).filter(Boolean).length > 2 && ( + setFilter(v as Filter)} + className="self-start" + items={FILTERS.filter((f) => n[f.value]).map((f) => ({ + value: f.value, + label: ( + <> + {f.label} {n[f.value]} + + ), + }))} + /> + )} +
+ + + + + + + + + + + + + {shown.map((r) => { + const last = lastOf(r.running ? "running" : r.last_status); + const why = noNext(r); + return ( + + + + + + + + + ); + })} + +
WhatWhenNext runLast runOn + Actions +
+
+ + {r.name} + + {whatText(r)} +
+
+ {r.text} + {(r.cron || r.on === "at") && ( + + {r.cron && {r.cron} · } + {r.timezone} + + )} + + {r.next_run_at ? ( + + ) : ( + {why ?? "—"} + )} + + {r.last_run_at || r.running ? ( +
+ + {last.label} + + {r.last_run_at && } +
+ ) : ( + Never run + )} +
+ switchTo(r, v)} + /> + +
+ setEditing(r)} + > + + + +
+
+
+

+ Run now works when something is switched off too. An automation’s switch turns the whole automation on or + off, whatever starts it. +

+ + )} + {editing && setEditing(null)} />} + !o && setOverBudget(null)} + title="Run it over budget?" + description={overBudget?.why.replace(/ Run it anyway with over_budget\.$/, "")} + actions={ + <> + + + + } + /> +
+ ); +} diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index 2d887e8f9..c80b73a78 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -28865,6 +28865,181 @@ } } }, + "/api/v1/schedules": { + "get": { + "tags": [ + "schedules" + ], + "summary": "List Schedules", + "description": "Everything that runs on a clock that you manage, soonest first: for admins every routine (those run only by\nhand too) and the scheduled backup; for everyone the schedule and at triggers of their automations. Each with\nwhen it runs in words, its next and last run, how that went and whether it's on.", + "operationId": "list_schedules", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScheduleCatalog" + } + } + } + } + } + } + }, + "/api/v1/schedules/{sid}": { + "get": { + "tags": [ + "schedules" + ], + "summary": "Get Schedule", + "operationId": "get_schedule", + "parameters": [ + { + "name": "sid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Sid" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Schedule" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "patch": { + "tags": [ + "schedules" + ], + "summary": "Change Schedule", + "description": "Change when it runs or switch it on or off; give only what changes. A routine's `cron: null` runs it only by\nhand. Switching an automation's schedule switches the whole automation (every trigger it has). Switching the\nbackup off clears backups.schedule; switching it on needs a cron.", + "operationId": "change_schedule", + "parameters": [ + { + "name": "sid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Sid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScheduleChange" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Schedule" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/schedules/{sid}/run": { + "post": { + "tags": [ + "schedules" + ], + "summary": "Run Schedule", + "description": "Run it now, even when it's off: a routine as soon as the scheduler next looks (within half a minute), an\nautomation here and now as its trigger would when its time comes, the backup now (it can take a while). A run over\na budget is refused (routines: 409) or held for your pick (automations) unless over_budget is true.", + "operationId": "run_schedule", + "parameters": [ + { + "name": "sid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Sid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/ScheduleRun" + }, + { + "type": "null" + } + ], + "title": "Body" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScheduleStarted" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, "/api/v1/sensors": { "get": { "tags": [ @@ -63879,6 +64054,259 @@ ], "title": "SavedView" }, + "Schedule": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "routine:, automation:: or backups" + }, + "kind": { + "type": "string", + "enum": [ + "routine", + "automation", + "backups" + ], + "title": "Kind" + }, + "name": { + "type": "string", + "title": "Name", + "description": "the routine's or automation's name" + }, + "trigger": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Trigger", + "description": "an automation's trigger (its `as`)" + }, + "on": { + "type": "string", + "enum": [ + "schedule", + "at", + "manual" + ], + "title": "On", + "description": "schedule: repeats on a cron; at: once, at a time; manual: no schedule (a routine run by hand, no backups)" + }, + "cron": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Cron", + "description": "five-field cron (minute hour day month weekday) or @daily..." + }, + "at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "At", + "description": "an at trigger's time (ISO 8601, in its time zone when it names none)" + }, + "timezone": { + "type": "string", + "title": "Timezone", + "default": "UTC" + }, + "text": { + "type": "string", + "title": "Text", + "description": "when it runs, in words: every weekday at 07:00, once on Fri 16 Oct at 07:00, ..." + }, + "enabled": { + "type": "boolean", + "title": "Enabled", + "description": "whether it runs on its own (for an automation: the whole automation is on)" + }, + "state": { + "type": "string", + "title": "State", + "description": "on, off or running (routines, the backup); waiting, done (an at trigger whose time came), missed, failed or off (automations)" + }, + "next_run_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Next Run At", + "description": "when it runs next (UTC); none while it's off or has no schedule" + }, + "last_run_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Run At" + }, + "last_status": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Status", + "description": "how its last run went (done, error, failed, partly, skipped, ...)" + }, + "running": { + "type": "boolean", + "title": "Running", + "default": false + }, + "href": { + "type": "string", + "title": "Href", + "description": "its page in the web app" + }, + "namespace_names": { + "anyOf": [ + { + "items": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Namespace Names", + "description": "the namespaces it works in; none for every one" + }, + "note": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Note", + "description": "something to know about it: why it doesn't run, its last error" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "id", + "kind", + "name", + "on", + "text", + "enabled", + "state", + "href" + ], + "title": "Schedule" + }, + "ScheduleCatalog": { + "properties": { + "schedules": { + "items": { + "$ref": "#/components/schemas/Schedule" + }, + "type": "array", + "title": "Schedules" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "schedules" + ], + "title": "ScheduleCatalog" + }, + "ScheduleChange": { + "properties": { + "cron": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Cron", + "description": "a new schedule (five-field cron or @daily...); null for a routine runs it only by hand, and for the backup stops scheduled backups" + }, + "at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "At", + "description": "a new time for an automation's at trigger, like 2026-11-02T07:30" + }, + "timezone": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Timezone", + "description": "a time zone, like Europe/London" + }, + "enabled": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Enabled", + "description": "switch it on or off: an automation's whole automation; the backup off clears its schedule" + } + }, + "additionalProperties": false, + "type": "object", + "title": "ScheduleChange" + }, "SchedulePreview": { "properties": { "schedule": { @@ -63911,6 +64339,70 @@ ], "title": "SchedulePreview" }, + "ScheduleRun": { + "properties": { + "over_budget": { + "type": "boolean", + "title": "Over Budget", + "description": "run it even though it's over a budget (docs/budgets.md)", + "default": false + } + }, + "additionalProperties": false, + "type": "object", + "title": "ScheduleRun" + }, + "ScheduleStarted": { + "properties": { + "status": { + "type": "string", + "title": "Status", + "description": "asked (a routine starts within half a minute), done, waiting, partly, failed, held (over a budget), skipped (its If was false), limited or off (automations), or done for a backup" + }, + "why": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Why", + "description": "why it didn't run, or was held" + }, + "run": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Run", + "description": "an automation's run (GET /api/v1/automations/runs/{run})" + }, + "backup": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Backup", + "description": "the backup it took" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "status" + ], + "title": "ScheduleStarted" + }, "SearchCreate": { "properties": { "q": { From b3213e93f0ce6a7fb732f752ce10f101de5a7409 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 01:23:51 +0000 Subject: [PATCH 2/4] fix(schedules): take the nav row Routines had so the phone nav fits as before The clicks check found Admin one swipe further down on a phone with a new nav row. Schedules now has Routines' row (the Routines page and New routine open from its top), the routine-create journey goes through it, and isActive marks Schedules on /routines pages. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01NwZdhpvjjidN5Y45CLSi8m --- ci/clicks/journeys.mjs | 3 ++- docs/frontend.md | 6 ++++-- docs/processing.md | 4 ++-- docs/schedules.md | 4 +++- nextjs-frontend/__tests__/navigation.test.ts | 8 ++++++-- .../__tests__/schedules-page.test.tsx | 4 ++++ .../components/app-shell/nav-config.ts | 7 ++++--- .../components/schedules/schedules-page.tsx | 19 +++++++++++++++++-- 8 files changed, 42 insertions(+), 13 deletions(-) diff --git a/ci/clicks/journeys.mjs b/ci/clicks/journeys.mjs index 6cf75183d..79b727879 100644 --- a/ci/clicks/journeys.mjs +++ b/ci/clicks/journeys.mjs @@ -310,7 +310,8 @@ export const JOURNEYS = [ from: "/", async run(ctx) { const { page, meter } = ctx; - await go(ctx, "Routines"); + // routines are on the Schedules page (everything on a clock), which has New routine for admins + await go(ctx, "Schedules"); await meter.click(page.getByRole("main").getByRole("link", { name: "New routine" }), "New routine"); await page.getByRole("textbox", { name: "Name" }).waitFor(); // named for you await page.waitForFunction(() => document.activeElement?.tagName === "INPUT"); diff --git a/docs/frontend.md b/docs/frontend.md index 248bcca2f..cc2c77569 100644 --- a/docs/frontend.md +++ b/docs/frontend.md @@ -38,9 +38,11 @@ nextjs-frontend/ The nav rail (`components/app-shell/nav-config.ts`) is in four groups, each named above its first item (a line when the rail is collapsed to icons): what people use every day (Home, Library, Search, Chat, Notes), **Explore** what Lens -found (Timeline, Entities, Topics, Graph, Podcasts, Reports), **Automate** what runs by itself (Pipelines, Routines, +found (Timeline, Entities, Topics, Graph, Podcasts, Reports), **Automate** what runs by itself (Pipelines, Schedules, Extensions, Sensors, or Sources for people who aren't admins), and **Manage** Lens (Costs, Analytics, Settings, -Admin). Every page stays one click from Home; ⌘K reaches every page, recording and setting by name. +Admin). Every page stays one click from Home; ⌘K reaches every page, recording and setting by name. The nav fits a +phone screen without a swipe (`ci/clicks` counts one), so a new page shares a row rather than adding one: the Routines +page opens from Schedules, and workflows, templates and content types are tabs of Pipelines. ## Design system diff --git a/docs/processing.md b/docs/processing.md index 305373489..cdd7a0abd 100644 --- a/docs/processing.md +++ b/docs/processing.md @@ -732,8 +732,8 @@ now. Every 30 seconds, `lens worker` checks (and so does the API process when it never started twice at once, and one started in two processes runs once. Each run keeps what every action did and a log. -The [Schedules](schedules.md) page lists every routine next to the automations' schedules and the backup, to switch, -re-time and run each from one place. +The [Schedules](schedules.md) page (Automate › Schedules) lists every routine next to the automations' schedules and +the backup, to switch, re-time and run each from one place; the Routines page and New routine open from its top. ### Organising the graph diff --git a/docs/schedules.md b/docs/schedules.md index c21804c94..135940bde 100644 --- a/docs/schedules.md +++ b/docs/schedules.md @@ -2,7 +2,9 @@ Status: built. The Schedules page (Automate → Schedules) is Lens's crontab: everything that runs on a clock, in one list, soonest first, with a switch, Run now and a way to change when it runs. Agents get the same list and the same -changes over the API and MCP. +changes over the API and MCP. It has the place Routines had in the nav, so the nav still fits a phone screen: for +admins, the [Routines](processing.md#routines) page (the list, proposed graph changes and history) and New routine +are at the top of it. ## What is on it diff --git a/nextjs-frontend/__tests__/navigation.test.ts b/nextjs-frontend/__tests__/navigation.test.ts index f194dfa55..dbcdb9fac 100644 --- a/nextjs-frontend/__tests__/navigation.test.ts +++ b/nextjs-frontend/__tests__/navigation.test.ts @@ -33,12 +33,16 @@ describe("navigation", () => { ).toEqual(["Costs", "Analytics", "Settings", "Admin"]); }); - it("has Schedules, everything that runs on a clock, under Automate for everyone", () => { + it("has Schedules, everything that runs on a clock, under Automate for everyone, where Routines was", () => { for (const admin of [true, false]) { expect(navFor(admin).find((i) => i.href === "/schedules")?.group).toBe("Automate"); + // the Routines page opens from Schedules, so the nav is no longer than before (one phone screen) + expect(navFor(admin).find((i) => i.href === "/routines")).toBeUndefined(); } expect(isActive("/schedules", "/schedules")).toBe(true); - expect(isActive("/schedules", "/routines")).toBe(false); + expect(isActive("/routines", "/schedules")).toBe(true); + expect(isActive("/routines/3", "/schedules")).toBe(true); + expect(isActive("/routines/history", "/schedules")).toBe(true); }); it("matches the active section", () => { diff --git a/nextjs-frontend/__tests__/schedules-page.test.tsx b/nextjs-frontend/__tests__/schedules-page.test.tsx index f0e47b668..1a95e25f9 100644 --- a/nextjs-frontend/__tests__/schedules-page.test.tsx +++ b/nextjs-frontend/__tests__/schedules-page.test.tsx @@ -102,6 +102,9 @@ function wrap(ui: ReactNode) { test("lists every routine, automation schedule and the backup, each linking to its own page", async () => { wrap(); const table = await screen.findByRole("table", { name: "Schedules" }); + // the Routines page and a new routine are one click away, since Schedules has Routines' place in the nav + expect(screen.getByRole("link", { name: "Routines" })).toHaveAttribute("href", "/routines"); + expect(screen.getByRole("link", { name: "New routine" })).toHaveAttribute("href", "/routines/new"); expect(within(table).getByRole("link", { name: "Sync nightly" })).toHaveAttribute("href", "/routines/3"); expect(within(table).getByRole("link", { name: "Mornings" })).toHaveAttribute("href", "/automations/4"); expect(within(table).getByRole("link", { name: "Back up the database" })).toHaveAttribute( @@ -162,4 +165,5 @@ test("someone who isn't an admin sees their automations' schedules and no filter await screen.findByRole("table", { name: "Schedules" }); expect(screen.getByText(/your automations/)).toBeInTheDocument(); expect(screen.queryByRole("radiogroup", { name: "Show" })).not.toBeInTheDocument(); + expect(screen.queryByRole("link", { name: "New routine" })).not.toBeInTheDocument(); }); diff --git a/nextjs-frontend/components/app-shell/nav-config.ts b/nextjs-frontend/components/app-shell/nav-config.ts index 3637f7d05..dbdb59739 100644 --- a/nextjs-frontend/components/app-shell/nav-config.ts +++ b/nextjs-frontend/components/app-shell/nav-config.ts @@ -1,7 +1,6 @@ import { AlarmClock, Blocks, - CalendarClock, ChartLine, ChartNoAxesColumn, HardDriveDownload, @@ -73,9 +72,9 @@ export const NAV: NavItem[] = [ group: "Automate", }, { label: "Pipelines", href: "/pipelines", icon: Workflow, group: "Automate" }, - // everything that runs on a clock in one list: everyone has it, for the schedules of their own automations + // Everything that runs on a clock in one list: everyone has it, for the schedules of their own automations. It + // takes the row Routines had (the Routines page opens from it), so the nav fits a phone screen as before. { label: "Schedules", href: "/schedules", icon: AlarmClock, group: "Automate" }, - { label: "Routines", href: "/routines", icon: CalendarClock, adminOnly: true, group: "Automate" }, { label: "Extensions", href: "/extensions", icon: Blocks, group: "Automate" }, // Admins see every source as a sensor; members see the watched folders feeding their namespaces. { label: "Sensors", href: "/sensors", icon: RadioTower, adminOnly: true, group: "Automate" }, @@ -112,6 +111,8 @@ export function isActive(pathname: string, href: string): boolean { if (href === "/sources" && pathname === "/sensors") return true; // An entity's page is under /wiki, by name. if (href === "/entities" && pathname.startsWith("/wiki/")) return true; + // The Routines page (its list, proposed graph changes and history) opens from Schedules. + if (href === "/schedules" && (pathname === "/routines" || pathname.startsWith("/routines/"))) return true; // Speakers live in Settings; a speaker's profile keeps its own address. if (href === "/settings" && (pathname === "/speakers" || pathname.startsWith("/speakers/"))) return true; return pathname === href || pathname.startsWith(`${href}/`); diff --git a/nextjs-frontend/components/schedules/schedules-page.tsx b/nextjs-frontend/components/schedules/schedules-page.tsx index 7853b4759..af845ae74 100644 --- a/nextjs-frontend/components/schedules/schedules-page.tsx +++ b/nextjs-frontend/components/schedules/schedules-page.tsx @@ -1,7 +1,7 @@ "use client"; import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; -import { AlarmClock, Pencil, Play } from "lucide-react"; +import { AlarmClock, Pencil, Play, Plus } from "lucide-react"; import Link from "next/link"; import { useState } from "react"; @@ -212,7 +212,22 @@ export function SchedulesPage() { return (
-

Schedules

+
+

Schedules

+ {admin && ( + <> + {/* the Routines page (the list, proposed graph changes, history) lives behind this one */} + + + + )} +

Everything that runs on a clock, in one place:{" "} {admin ? "routines, your automations and backups" : "your automations"}. From db4e051b2cd8f13c6e313474d5591bc72dd40fc3 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 02:56:37 +0000 Subject: [PATCH 3/4] fix(schedules): one New routine on the page, in its header An empty Schedules page had New routine twice (the header and the empty state), which made the routine-create clicks journey's link ambiguous. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01NwZdhpvjjidN5Y45CLSi8m --- .../components/schedules/schedules-page.tsx | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/nextjs-frontend/components/schedules/schedules-page.tsx b/nextjs-frontend/components/schedules/schedules-page.tsx index af845ae74..329e8dfe3 100644 --- a/nextjs-frontend/components/schedules/schedules-page.tsx +++ b/nextjs-frontend/components/schedules/schedules-page.tsx @@ -248,17 +248,11 @@ export function SchedulesPage() { } title="Nothing runs on a clock yet" + // New routine is in the header already actions={ - <> - {admin && ( - - )} - - + } > A routine or an automation with a schedule shows here, with when it runs next, how it last went and a switch. From a4d90fa2bde76d39cf5556ea6f2c590ff2e46831 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 07:32:34 +0000 Subject: [PATCH 4/4] docs(requirements): list the assistant's answers about Lens itself as built #400 shipped in v0.15.0, so its In progress line failed make requirements on main. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01NwZdhpvjjidN5Y45CLSi8m --- README.md | 6 +++--- docs/requirements.md | 1 + 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2a8ecf84a..de675c918 100644 --- a/README.md +++ b/README.md @@ -86,11 +86,13 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p cost), opened from its header. It reads answers aloud with a speech provider, macOS `say` or StyleTTS2 on this machine (opt-in), any message in one click. Long conversations are summarised before they fill the model's context, and `/clear` and `/compact` start afresh or summarise now. Conversations title themselves after their first answer, unless - you name them. Each namespace can have its own assistant with + you name them. Questions about Lens itself (how to do something, what is turned on) are answered from its docs and + this server, cited. Each namespace can have its own assistant with its own name, instructions and memory, answering in Telegram and Slack (built in, with voice notes and files), in Discord, Matrix, WhatsApp and other chat rooms through Matterbridge, and by email at an address of its own that you email or forward things to. ([Chat](docs/assistant.md), [web search](docs/assistant.md#web-search-and-reading-pages), [mail, calendars and files](docs/assistant.md#mail-calendars-and-files), [code sandbox](docs/assistant.md#code-sandbox), [answer records](docs/assistant.md#what-each-answer-records), + [questions about Lens](docs/assistant.md#questions-about-lens-itself), [chat rooms](docs/chat-rooms.md), [email](docs/assistant-email.md), [speech providers](docs/speech-providers.md); [checks](docs/requirements.md#ask-and-get-cited-answers)) - **Extend the assistant.** Add tools (a prompt, a web request, a graph drawn on the canvas, or sandboxed Python), @@ -237,8 +239,6 @@ still loading. ([Components](docs/components.md), These are open pull requests, not yet part of Lens: -- **The assistant** answering questions about Lens itself, from its docs and this server - ([#400](https://github.com/adeelahmad/lense/pull/400)). - **Chat:** a conversation exported as Markdown, PDF or JSON ([#474](https://github.com/adeelahmad/lense/pull/474)). - **Pictures:** low-quality images enhanced before they're read ([#479](https://github.com/adeelahmad/lense/pull/479)). - **Web clipper:** signing in, or using your API token, not only an import webhook's diff --git a/docs/requirements.md b/docs/requirements.md index 23fae8de6..0244d7ddb 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -87,6 +87,7 @@ request, to another check that proves the same thing; loosening a requirement or | Each answer keeps a record of what produced it: the model, its tools, how long it took and what it cost | [test_chat_records.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_chat_records.py) `test_an_answer_records_what_produced_it`, `test_a_regenerated_answer_has_its_own_record`; [chat-details.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/chat-details.test.tsx) `says what produced it: model and host, scope, tools, use, tokens, cost, time and how it ended` | | Answers read aloud by a speech provider, macOS `say` or StyleTTS2 (opt-in) | [test_voice.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_voice.py) `test_answers_are_read_aloud_by_a_speech_model`; [test_speech.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_speech.py) `test_macos_say_reads_aloud_on_a_mac`, `test_styletts2_reads_aloud_from_its_own_service`; [styletts2.yml](https://github.com/adeelahmad/lense/blob/main/.github/workflows/styletts2.yml) `Read a sentence aloud` | | Any message read aloud in one click, one at a time, its audio kept so a replay costs nothing | [chat-read-aloud.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/chat-read-aloud.test.tsx) `plays an answer by the speech model in one click, stops on the next, and keeps its audio`, `reads one message at a time: starting another stops the first`, `reads a long answer piece by piece, asking for the next while one plays` | +| Questions about Lens itself answered from its docs and this server, cited, for people and for agents over MCP | [test_lens_help.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_lens_help.py) `test_the_assistant_answers_about_lens_itself`, `test_the_docs_are_found_by_words`, `test_agents_ask_lens_over_mcp` | | Conversations title themselves after their first answer, and a name you give is kept | [test_chat_titles.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_chat_titles.py) `test_a_first_answer_titles_the_conversation`, `test_a_title_you_give_is_kept`, `test_agents_rename_and_retitle_over_mcp` | | Long conversations summarised before they fill the model's context, and `/clear` and `/compact` | [test_compaction.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_compaction.py) `test_older_messages_are_folded_into_a_summary`, `test_the_context_window_is_the_model_servers`, `test_a_long_conversation_is_folded_in_runs_that_fit_the_summary_model`, `test_clear_starts_afresh_and_compact_folds_everything_now`, `test_commands_in_the_app` | | A namespace's own assistant, with its own name, instructions and memory | [test_ns_assistant.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_ns_assistant.py) `test_off_by_default_and_owners_turn_it_on`, `test_remembers_across_conversations_with_citations`; [ns-assistant.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/ns-assistant.test.tsx) `saving a name and forgetting a memory` |