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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,16 +164,18 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
numbers, lists, times, days, whether a value changed and whether something like it happened before in their
namespaces) and let a decision model pick the branch, 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, and an Entity filter node keeps the entities you want. 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. An automation's
workflow is drawn and tried on the workflow canvas, with its actions in the palette; the studio's builder is
planned. ([Processing](docs/processing.md#workflows-and-the-canvas),
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, and an Entity filter node keeps the entities you want. 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. An automation's workflow is drawn and tried on the workflow canvas, with its actions in
the palette; the studio's builder is planned. ([Processing](docs/processing.md#workflows-and-the-canvas),
[converting assets](docs/processing.md#converting-assets), [notifications](docs/notifications.md),
[automations](docs/automations.md),
[approvals](docs/automations.md#approvals), [timeline](docs/timeline.md); [checks](docs/requirements.md#automate-it))
[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
Expand Down
3 changes: 2 additions & 1 deletion ci/clicks/journeys.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -313,7 +313,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");
Expand Down
13 changes: 13 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

```
Expand Down
3 changes: 3 additions & 0 deletions docs/automations.md
Original file line number Diff line number Diff line change
Expand Up @@ -822,6 +822,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
Expand Down
6 changes: 4 additions & 2 deletions docs/frontend.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
3 changes: 3 additions & 0 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,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 |
Expand Down
3 changes: 3 additions & 0 deletions docs/processing.md
Original file line number Diff line number Diff line change
Expand Up @@ -792,6 +792,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 (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

A workflow's scope is assets (above), the graph, or an event: an automation's workflow, run by its automation
Expand Down
1 change: 1 addition & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,7 @@ request, to another check that proves the same thing; loosening a requirement or
| 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` |
| An Entity filter node keeps a list's entities by type, stop list, length, pattern or how often they're said | [test_flow.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_flow.py) `test_entity_filter_keeps_the_entities_asked_for`; [workflow-flow.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/workflow-flow.test.ts) `an entity filter says what it keeps and refuses lowercase types` |
| 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` |
Expand Down
57 changes: 57 additions & 0 deletions docs/schedules.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# 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. 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

| 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.
Loading
Loading