Handoff
System of record for handoffs — stack-ranked priority lists, dependencies, agent conversations, and a restorable archive
Open it
Routes
| Protocol | Address | JAR | Provider |
|---|---|---|---|
| https | handoff.wasmserver.com | redirect-to-https.jar | danger_jarfile |
| https | www.handoff.wasmserver.com | handoff-wui.jar | danger_jarfile |
| url | url://handoff/ | handoff-service-server.jar | danger_jarfile |
Repositories
| Repository | Layer | Description |
|---|---|---|
| HandoffApi | api | API interfaces, data types, and canonical document serialization (handoff:api) |
| HandoffEmbedded | embedded | In-process implementation; JSON persistence via injected Okio FileSystem (handoff:embedded) |
| HandoffServiceServer | serviceserver | url://handoff/ protocol server (handoff:serviceserver) |
| HandoffCli | cli | handoff-cli command-line client (handoff:cli) |
| HandoffWui | wui | Web UI: priority list, detail pages, ArchiveArea (handoff:wui) |
Depends on
url://vpn.<host-id>.aiclisupervisor/— *optional*; supplies the cached fleet snapshot from which each conversation's Active/Idle status is derived. Handoff functions without it (conversations simply carry no live activity).
Documentation Edit this page
Handoff
The system of record for handoffs — the point-in-time write-ups that let a different person or agent pick up an in-flight effort cold. Handoff owns the handoff documents, orders them into stack-ranked priority lists, tracks handoff-to-handoff dependencies (computing Blocked status), links each handoff to the live agent sessions working it (computing Active/Idle), and archives handoffs restorably on completion. It replaces the older PlanRepository/handoffs/ git/PR workflow, and during a transitional bake period is kept bidirectionally synchronized with that directory.
See the Handoff project overview for the full architecture and design.
Routes
Both run as danger_jarfile (not cloudrunjar) because they connect to the P2P network.
The WUI is served from www.handoff.wasmserver.com; the apex handoff.wasmserver.com is a permanent redirect to it (redirect-to-https.jar).
Architecture
Browser ──HTTPS──► HandoffWui (handoff-wui.jar, www.handoff.wasmserver.com)
│
│ url://handoff/ via UrlResolver
▼
HandoffServiceServer (url://handoff/)
│
▼
HandoffEmbedded (domain logic)
│ persists to HANDOFF_STATE_DIR (JSON, atomic move-on-write)
│
┌──────────┴───────────────┐
│ (optional) │ (optional, transitional)
▼ ▼
AiCliSupervisorManager PlanRepository/handoffs/ (git)
(conversation activity) two-way sync during bake period
Configuration
HandoffServiceServer environment variables:
| Variable | Required | Purpose |
|---|---|---|
HANDOFF_STATE_DIR |
Yes (defaults to ~/.handoff) |
Durable state directory — mount from persistent host storage; a container-local directory loses all handoffs on container replacement |
URL_BIND_DOMAIN |
For CN lazy-start | ContainerNursery lazy-start bind domain; supports ${PORT} substitution |
PORT |
With CN lazy-start | Port substituted into URL_BIND_DOMAIN |
AICLI_SUPERVISOR_MANAGER_URL |
No | When set, injects the AiCliSupervisorManager dependency used to compute conversation Active/Idle status; declare it in the route's dependencies array so CN pre-warms it during cold start |
HANDOFF_GIT_SYNC_REPO |
No | Enables the transitional bidirectional PlanRepository/handoffs/ sync |
HANDOFF_GIT_SYNC_INTERVAL_MS |
No | Sync interval (default 300000, i.e. 5 minutes) |
CLIENT_JAR_PATH |
No | Filesystem fallback for the SJVM client bytecode JAR |
HandoffWui connects to the service via HANDOFF_SERVICE_URL (default url://handoff/) and listens on http://0.0.0.0:${PORT} (default 8080).
Dependents
- The
create-handoffskill and agents drive the service throughhandoff-cliinstead of the git/PR workflow.
Deployment
# Deploy the url:// service (danger_jarfile — connects to the P2P network)
container-nursery-cli deploy --jar handoff-service-server.jar --route "url://handoff/"
# Deploy the WUI
container-nursery-cli deploy --jar handoff-wui.jar --route "https://www.handoff.wasmserver.com"
Ensure HANDOFF_STATE_DIR is mounted from persistent host storage before serving traffic.
Health Checks
- CLI:
handoff-cli health(printsOK, or{"status":"OK"}with--json) - WUI:
https://handoff.wasmserver.com/health(service-backed liveness) should return 200 - Production Health: check productionhealth.wasmserver.com for status
Notes
- The
PlanRepository/handoffs/git sync is explicitly transitional: during the bake period both sides are kept aligned (service wins on conflict); once the service has baked, the git flow is retired. - All durable state lives in
HANDOFF_STATE_DIR; the WUI and ServiceServer are otherwise ephemeral and may be restarted at any time.
Read at commit 45ba0b30ed3b