Skip to content

local-runtime.md

Latest commit

 

History

History
135 lines (104 loc) · 7.83 KB

local-runtime.md

File metadata and controls

135 lines (104 loc) · 7.83 KB

Alice vNext Local Runtime

Alice vNext now includes a local scheduler runtime for running governed Alice Brain workflows in the background. This is a local alpha runtime, not a hosted scheduler service.

What It Runs

The daemon wraps:

alicebot vnext scheduler daemon start

In foreground mode, it polls alicebot vnext scheduler run-due behavior on an interval and persists status to ~/.alicebot/vnext-scheduler/scheduler-status.json. In background mode, it spawns the same foreground worker as a local process and records a pid file, status file, and log file.

Commands

alicebot vnext scheduler daemon start
alicebot vnext scheduler daemon start --foreground
alicebot vnext scheduler daemon start --foreground --once
alicebot vnext scheduler daemon status
alicebot vnext scheduler daemon stop
alicebot vnext scheduler runs
alicebot vnext scheduler failures
alicebot vnext agents policy-telemetry
alicebot vnext smoke local-runtime
alicebot vnext smoke model-backed
alicebot vnext connectors status
alicebot vnext connectors health
alicebot vnext dogfooding dashboard
alicebot vnext migrations status
alicebot vnext doctor --fix-safe
alicebot vnext smoke live-capture-connectors
alicebot vnext smoke capture-to-brief
alicebot vnext smoke connector-hardening
alicebot vnext smoke local-cors
alicebot vnext smoke secret-redaction
alicebot vnext smoke dogfood-doctor
alicebot vnext smoke agent-integration-pack
alicebot vnext alpha check

Useful options:

  • --interval-seconds: due-scan polling interval. Default: 60.
  • --limit: maximum due workflows per scan. Default: 10.
  • --pid-file: daemon pid path. Default: ~/.alicebot/vnext-scheduler/scheduler.pid.
  • --status-file: daemon status JSON path. Default: ~/.alicebot/vnext-scheduler/scheduler-status.json.
  • --log-file: daemon log path. Default: ~/.alicebot/vnext-scheduler/scheduler.log.

Scheduler Guarantees

  • Workflows remain disabled by default.
  • Disabled workflows are not run.
  • Paused workflows are not run.
  • Due scans use a per-workflow Postgres advisory lock to avoid duplicate concurrent runs for the same workflow.
  • Daily Brief and Weekly Synthesis scheduled runs still produce reviewable generated artifacts.
  • Connection Report, Contradiction Report, Open Loop Review, and Project Update Scan now produce deterministic reviewable artifacts from scheduled runs.
  • Scheduled artifacts include scheduler trace metadata: generated_by, workflow_type, scheduler_run_id, trace_id, source_refs, domain, sensitivity, and review_status.
  • Scheduled workflows can run with --generation-mode deterministic or --generation-mode model_backed. Model-backed scheduled runs store prompt hashes, input context hashes, provider/model metadata, source-grounded sections, and routing policy.
  • Generated artifacts and agent proposals are not auto-promoted into trusted memory.

Operator Visibility

The /vnext Schedules surface shows daemon posture, last due scan, next due workflow, currently running workflow, recent failures, last successful run per workflow, and run history. The Timeline surface remains backed by the append-only event log. Agent Activity includes policy blocks, filters, review-gated decisions, workflow triggers, memory proposals, and artifact generation telemetry.

The /vnext Home, Inbox, Trace, Doctor, and Connectors surfaces also show dogfooding and capture health: captures by connector, captures today/week, candidate memory creation, source review/archive posture, capture-to-brief traceability, doctor readiness, artifact ratings, useful-insight feedback, connector enabled/configured state, persisted settings, secret presence, cursors, dedupe, failures, and last sync posture.

The API exposes the same local runtime posture through:

  • GET /v0/vnext/scheduler/status
  • GET /v0/vnext/scheduler/runs
  • GET /v0/vnext/scheduler/failures
  • POST /v0/vnext/scheduler/run-due
  • GET /v0/vnext/agents/policy-telemetry
  • GET /v0/vnext/connectors/health
  • GET /v0/vnext/connectors/status
  • PATCH /v0/vnext/connectors/{connector_name}/config
  • POST /v0/vnext/connectors/telegram/sync
  • POST /v0/vnext/connectors/local-folder/sync
  • GET /v0/vnext/dogfooding
  • GET /v0/vnext/doctor
  • POST /v0/vnext/doctor/run
  • POST /v0/vnext/sources/{source_id}/review
  • GET /v0/vnext/traces/sources/{source_id}
  • GET /v0/vnext/traces/artifacts/{artifact_id}

Scheduler workflow configuration can also carry model_options so due scans run model-backed workflows only when policy and routing allow them.

macOS launchd

Use docs/runbooks/vnext-local-scheduler.launchd.plist as the template. Replace the paths, ALICE_DATABASE_URL, and ALICE_USER_ID values before loading it.

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.alicebot.vnext-scheduler.plist
launchctl kickstart -k gui/$(id -u)/com.alicebot.vnext-scheduler
launchctl bootout gui/$(id -u)/com.alicebot.vnext-scheduler

Linux systemd

Use docs/runbooks/vnext-local-scheduler.service as the template. Replace the working directory, environment variables, user, and venv path before enabling it.

systemctl --user daemon-reload
systemctl --user enable --now alicebot-vnext-scheduler.service
systemctl --user status alicebot-vnext-scheduler.service
systemctl --user stop alicebot-vnext-scheduler.service

Validation

The local runtime smoke is Postgres-backed:

alicebot vnext smoke local-runtime
alicebot vnext smoke model-backed
alicebot vnext smoke live-capture-connectors
alicebot vnext smoke capture-to-brief
alicebot vnext smoke connector-hardening
alicebot vnext smoke local-cors
alicebot vnext smoke secret-redaction
alicebot vnext smoke dogfood-doctor
alicebot vnext smoke operator-console

It seeds a small local-runtime fixture, marks all six scheduler workflows due, runs the foreground daemon once, and checks that each workflow produces a reviewable artifact with scheduler metadata.

The model-backed smoke seeds a scheduled model-backed workflow and verifies that the due scan creates a reviewable artifact with local-only routing, provider metadata, source references, and the required grounded output sections.

The live-capture connector smoke verifies allowlisted Telegram import, rejected Telegram chat isolation, local folder import with generated-folder ignore rules, browser clipper capture, review-only agent output ingestion, and connector health telemetry. The capture-to-brief smoke verifies that a fresh browser clip can enter retrieval, produce a reviewable Daily Brief, record a quality rating, and show up in dogfooding telemetry.

The connector-hardening smoke verifies dedicated connector settings/state rows, Telegram cursor persistence, rejected-chat logging, local-folder generated-output ignores, restart dedupe, and health counters. The local-cors smoke verifies the explicit localhost CORS allowlist and public browser API env needed by /vnext?mode=live. The secret-redaction smoke verifies that Telegram and browser clipper secrets never appear in persisted source/event output. The dogfood-doctor smoke verifies migration readiness, default connector rows, scheduler posture, configured secret references, and blocking failure counts. The operator-console smoke verifies the live daily operation path across source review, memory review, artifact review/rating, source-backed open loops, scheduler run-now, connector health, doctor readiness, event logging, and capture-to-brief traceability.

The agent-integration-pack smoke verifies the public alpha agent path: OpenClaw identity, scoped project context, review-only output ingestion, review-only memory proposal creation, no auto-promotion, event logging, restricted-domain policy blocking, and Agent Activity visibility. The alpha check wraps readiness posture and the core smokes into one command for technical design partners.