Tools
Claw_agenda
By An Agenda plugin for Openclaw
Install
npm install --frozen-lockfileREADME
# Agenda
An OpenClaw plugin for a private calendar website, desktop completion feedback,
and agent-managed tasks.
This repository owns the plugin source. The installed copy lives at
`~/.openclaw/extensions/agenda`; make code changes here, then build and deploy.
Personal sentinel workflows remain in the installed `operations/` directory.
The live database remains at `~/.openclaw/plugins/agenda/agenda.sqlite` and is
never included in this repository or a code deployment.
## Development
Use Node.js 24.16+ (below 25) or 26.1+, and pnpm 12.9.1. Keep the existing
OpenClaw checkout at `../AgileClaw`. The development dependency links to that
checkout's public `openclaw/plugin-sdk/*` exports; it does not install or rebuild
OpenClaw. Build OpenClaw separately if its SDK artifacts are missing.
```sh
pnpm install --frozen-lockfile
pnpm build
pnpm test
```
`pnpm typecheck` requires local declarations for the host's private SQLite runtime
facades. OpenClaw intentionally publishes these facades as JavaScript-only
exports; an ordinary build does not emit their declarations. Generate them from
the maintained OpenClaw sources with its private-QA declaration build, then run
Agenda's full typecheck:
```sh
cd ../AgileClaw
OPENCLAW_BUILD_PRIVATE_QA=1 pnpm build:plugin-sdk:dts
cd ../agenda
pnpm typecheck
```
This declaration-only build preserves the host's runtime JavaScript and does not
require restarting the Gateway. Keep the generated declarations local; they do
not turn these internal facades into a public third-party SDK contract. Agenda
uses the linked host's real types, without ambient declarations or untyped
substitutes.
`web/` contains the calendar UI. `src/` contains the HTTP server, task contracts,
and SQLite worker. `skills/` contains the bundled Agenda skill. Builds produce
`assets/` and `dist/`; dependencies and generated output are Git-ignored.
## Deploy an update
For changes that keep the installed runtime dependencies unchanged, run the
checks above, then copy the built output and bundled metadata from this checkout:
```sh
agenda_plugin_dir="$HOME/.openclaw/extensions/agenda"
cp -R dist/. "$agenda_plugin_dir/dist/"
cp -R assets/. "$agenda_plugin_dir/assets/"
cp openclaw.plugin.json "$agenda_plugin_dir/"
cp -R skills/. "$agenda_plugin_dir/skills/"
```
Then use OpenClaw's native plugin reload from the OpenClaw checkout:
```sh
cd ../AgileClaw
pnpm openclaw plugins reload agenda --wait --json
```
The reload waits for in-flight plugin work and refreshes the website's cached
assets. Refresh the desktop page after it completes. Dependency changes need
OpenClaw's plugin installation/update workflow rather than these output-only
copy commands. Preserve the installed `operations/` directory and live database.
The website listens at `http://127.0.0.1:18810/agenda/`. Add `?display=desktop`
for the desktop layout; `theme=dark` or `theme=light` overrides system appearance,
and `dock=96` controls the reserved bottom strip in CSS pixels.
The desktop day view centers the current Beijing time and follows it as time
passes. Scrolling manually pauses following; click **现在** to resume. Selecting
the other half-day keeps that period open for browsing.
## Completion feedback
Check **本段完成** on a desktop card to finish that time block. The task stays
active. Open its details and choose **整项已完成** when the whole task is done.
Today's completed cards remain visible; future blocks for a completed task leave
the active calendar. The displayed time state never implies completion.
Completion is saved before replanning begins. The feedback area shows waiting,
running, adjusted, unchanged, or failed with a short Chinese explanation. Undo
restores only that completion state and requests a fresh assessment; it never
restores an older calendar. A failed assessment does not discard completion.
**重试调整** retries an assessment; an uncertain browser submission is reconciled
against its operation receipt before the exact request can be replayed.
Agenda wakes the unique enabled `main` agent job named `sentinel` through the
host's service-owned `getCron().enqueueRun(..., "if-enabled")` capability. It does
not create a job, enable a disabled scheduler, select another model, or add a
second planner. Missing, ambiguous, disabled, or unsupported scheduling appears
as an actionable feedback error. Feedback arriving during a run is retained for
that run's assessment or a subsequent run. Existing routine delivery remains
unchanged; this feature sends no additional chat notification.
The Agent reads progress and feedback through `agenda read` and submits
`change.feedbackResults` through `agenda apply` together with any plan changes.
Each result includes the feedback `id`, `status` (adjusted/unchanged/error), and
`summary`. A successful run without an explicit result is not reported as a
successful adjustment. Only the tool changes execution plans; the website's
`POST /agenda/api/feedback` accepts completion, undo, and assessment retry only.
Writes require a same-origin JSON request and an `X-Agenda-CSRF` token from
`GET /agenda/api/session`. Local loopback hosts and exact hosts from the existing
Gateway `gateway.controlUi.allowedOrigins` setting are admitted; unknown hosts
are refused before serving data or a token to prevent DNS rebinding. Proxies
must preserve the public Host header. Keep
the existing private access boundary: the CSRF token prevents cross-site writes,
and is not a replacement for network access control. Gateway credentials never
enter the page.
The Agent chooses how far ahead to reassess and whether freed time should become
rest or another task. Existing deadlines, source coverage, personal scheduling
rules, courses, meetings, and locks remain authoritative. A completed segment is
historical progress, not evidence that its task or estimated workload is finished.
## Database upgrade and recovery
Schema v2 adds block progress and durable feedback/result records, plus a feedback
reference on operation receipts. The SQLite worker migrates v1 at admission;
existing tasks, blocks, sources, and receipts remain intact. Before migrating an
existing v1 database it writes a consistent, WAL-aware SQLite snapshot named
`agenda.sqlite.pre-v2-<unique-id>.bak` beside the database with private permissions.
New databases need no pre-upgrade backup. No second task store is introduced.
Refreshes and plugin reloads recover saved feedback. Run admission is reconciled
through the native scheduler; uncertain starts are not blindly retried. Older
plugin versions cannot open v2. To downgrade, stop only Agenda, preserve the v2
database and its WAL family, and restore the pre-v2 snapshot using the database
owner's offline recovery procedure. That restores the pre-upgrade data and loses
later changes, so do not substitute an old database while the plugin is active.
Validation uses isolated SQLite databases, real HTTP feedback requests, the
actual agenda tool, and a controlled native-scheduler boundary. UI proof uses
synthetic schedules. These checks do not claim a live model's scheduling quality
or modify the operator's live tasks.
## Verified installed build
On October 22, 2026, the completion-feedback source passed the standalone build,
store/HTTP/replanner/calendar tests, and full typecheck against the linked
OpenClaw host. The rebuilt runtime, website assets, plugin manifest, and Agenda
skill matched the installed files byte-for-byte. No reload or task-data changes
were needed to record this deployment.
The deployed runtime and website are identified by these SHA-256 digests:
| Installed file | SHA-256 |
| --- | --- |
| `dist/index.js` | `f6e9227292372a3c3edbdab93af6e270760fdf222dd85f65eff9466d274d3221` |
| `dist/src/sqlite.worker.js` | `2dbe584cdcafdf7522d2a4f4073ec149d609b86d83676f76e233a76c2ba96608` |
| `assets/app.js` | `c311ecafe51c7368a748287c7be13b8de873e5a599895edc0dda17fa2c0d1712` |
| `assets/app.css` | `bb10d9c1b0f400222daa629684d687cb6147325553b8fa7f8d4af948e0551cb9` |
The installed source files can lag behind the deployed bundles. Make subsequent
changes in this repository and rebuild; do not reconstruct source from the
installation or deploy its stale source files.
## History and recovery
The first commit imports the installed source as it existed on October 21, 2026,
including the adaptive half-day desktop calendar and dark mode. Later commits
record the standalone development setup. No remote repository is configured.
To inspect a change, use `git log --oneline` and `git diff <older>..<newer>`.
To restore an earlier implementation, revert the relevant commit, run the checks,
then build and deploy again. Reverting plugin code does not restore task data;
manage database backups separately through its existing owner.
tools
Comments
Sign in to leave a comment