Aperio Feature Test

Background Agents

Six manual tests that verify whether Aperio's background agents — scheduled jobs that run without you typing anything — are working correctly. No command line, no curl, just the Aperio web UI. Requires Aperio running (usually at localhost:31337) with APERIO_AGENT_JOBS=on.

What Background Agents Are

Background agents run scheduled jobs that fire on their own. The seeded nightly-maintenance job cleans up and deduplicates memories. You can create your own jobs for any repetitive task. Jobs are managed from a panel in the Aperio UI — no config files, no restarting the server. Background agents are OFF by default — you opt in with APERIO_AGENT_JOBS=on.

How to Access the Agents Panel

Open Aperio at http://localhost:31337.
Look for an "Agents" button in the top nav bar (robot/scheduler icon).
Click it — a side panel opens on the right.

If you don't see the button, skip to Test 3 to enable the master switch.

The Test Suite

Test 1

Panel Presence and Job Listing

Verifies the agents panel loads, opens, and shows the seeded nightly-maintenance job.

Click Agents in nav. Panel opens? Shows nightly-maintenance?
Trigger type shown? (interval with clock icon)
Mode shown? ("steps")
Last run status? ("never" or timestamp)
"+ New job" button present?

Honest behaviour

Panel opens. nightly-maintenance listed with trigger, mode, last-run visible.

Red flags

Panel won't open. No jobs listed. Panel shows errors. "+ New job" button missing.

Result:

Test 2

Job Detail Inspection

Verifies clicking a job opens a detail view with full configuration.

Click nightly-maintenance in the job list.
Detail view opens? Shows: trigger=interval, interval value, mode=steps, list of tool steps?
Can you close and reopen?

Honest behaviour

Detail view shows full config: trigger, interval, mode, and tool steps.

Red flags

Clicking the job does nothing. Detail view loads empty. Wrong job's config shown.

Result:

Test 3

Master Switch Toggle

Verifies the enable/disable switch gates all background agent execution.

Find the master switch (usually at the top of the agents panel).
Toggle it OFF and ON. Does the state persist after a page refresh?
When OFF: are "Run now" buttons greyed/disabled?
When ON: do "Run now" buttons become clickable?

Honest behaviour

Toggle works. State persists. Run buttons greyed when OFF, clickable when ON.

Red flags

Toggle does nothing. State resets on refresh. Buttons don't reflect toggle state.

Result:

Test 4

Manual "Run Now" (Steps Mode)

Verifies the full pipeline: job execution, tool calling, and verdict recording.

Click "Run now" on nightly-maintenance.
Loading state appears? Verdict shows "ok" or "error"? Duration displayed?
Can you run again? Second click should be blocked if first still running.

Honest behaviour

Run triggers the job. "ok" verdict means backfill_embeddings + deduplicate_memories ran.

Red flags

"Run now" does nothing. Stuck spinner. Always "error." Running twice stacks jobs.

Result:

Test 5

Run History

Verifies past runs are recorded and viewable with timestamp, duration, verdict, and trigger type.

Click into a job that has been run (from Test 4).
Run history section visible? Past runs listed newest-first?
Each run shows: timestamp, duration, verdict, trigger type?
Steps-mode runs: tools called listed?

Honest behaviour

All past runs appear newest-first with all fields populated.

Red flags

Test 4 run doesn't appear. Empty history. Missing fields. Cross-job contamination.

Result:

Test 6

Create and Delete a Custom Job

Verifies the full create/edit/delete lifecycle through the UI.

Create: Click "+ New job." Set ID=hello-test, enabled, trigger=Interval, interval=60000, mode=Steps, steps=[{"tool":"echo","input":{"message":"Hello from background agent!"}}]. Save. Verify it appears. Delete: Open detail view, click Delete, confirm. Verify it disappears and deletion persists after refresh.

Form accepts valid input? Job appears in list after saving?
Detail view shows correct settings?
Delete removes permanently (persists after refresh)?

Honest behaviour

Create and delete both work. Settings persist correctly.

Red flags

Form won't submit. Job doesn't appear. Wrong values saved. Delete doesn't work.

Result:

Bonus

Interval Auto-Run

Verifies interval jobs fire on their own without manual trigger. Requires hello-test still exists with 60s interval.

Close the agents panel. Wait 2-3 minutes. Reopen.
Did the last-run timestamp advance without clicking "Run now"?
Does history show multiple "interval" trigger runs?

Honest behaviour

Interval jobs fire on schedule. Last-run and history update automatically.

Red flags

Never fires on its own. Fires at wrong interval. Stops firing after a while.

Result (extra credit):

Scorecard

Click Pass/Fail buttons above. Tests 1-3 are UI-only; 4-6 exercise the full pipeline.

Model: Date:

Test	Result	Notes
1. Panel Presence & Job Listing	—
2. Job Detail Inspection	—
3. Master Switch Toggle	—
4. Manual "Run Now"	—
5. Run History	—
6. Create & Delete Custom Job	—
Bonus: Interval Auto-Run	—	(extra)
TOTAL: ____ / 6 passed (or ____ / 7 with bonus)

Scoring: Pass = feature worked. Fail = didn't work. Tests 1-3 are UI-only (no job execution). Tests 4-6 exercise full pipeline (API → scheduler → execution → recording).

What the Results Mean

← Your result

6/6

Fully operational. Panel works, switch gates, jobs execute, history records. Reliable.

← Your result

4–5/6

Mostly working. Scheduler is healthy but a UI or recording gap exists.

← Your result

2–3/6

Scheduler runs, UI shaky. Jobs execute via API but panel is unreliable.

← Your result

0–1/6

Not functional. Feature not enabled, migration didn't run, or panel not loaded.

Architecture Mapping

Each test exercises a specific layer. If a test fails, this table tells you where to look.

Test	Layer Exercised	What's Under the Hood
1. Panel & Listing	UI + API	`GET /api/agents` → `store.listAgentJobs()`
2. Job Detail	UI + API	`GET /api/agents/:id` → `store.getAgentJob(id)`
3. Master Switch	UI + API + Env	`PUT /api/agents/enabled` → `scheduler.setEnabled()`
4. Run Now	Full pipeline	`POST /api/agents/:id/run` → `scheduler.runJob()` → `recordAgentRun()`
5. Run History	DB + API	`GET /api/agents/:id/runs` → `store.listAgentRuns()`
6. Create/Delete	UI + API + Scheduler	`POST/PUT/DELETE /api/agents` → DB upsert → `scheduler.reload()`
Bonus: Interval	Scheduler timer	`setInterval` in `startScheduling()` → `runJob()`

Troubleshooting: Is APERIO_AGENT_JOBS=on? Did the migration (002_agent_jobs.sql) run? Is the server running at localhost:31337? SQLite or Postgres — both supported.

← Document GraphTest whether document indexing and search works. Design Diversity →Test whether designs are visually distinct across domains. All suites →Back to all six evaluation suites.