Problem
When the user starts an Activity, failures due to infrastructure problems (e.g., Ollama unreachable, model not available) are only discovered after the activity has run — every photo ends up failed with the same error, and there is no actionable feedback upfront.
The user has no opportunity to fix the problem before wasting time waiting for a doomed activity.
Proposed solution
API — new preflight endpoint
Add a POST /api/activities/preflight endpoint that accepts the same parameters as activity creation and checks whether all prerequisites are satisfied.
Example request:
{
"provider": "ollama",
"model": "llava"
}
Example response when prerequisites are not met:
{
"ready": false,
"checks": [
{ "name": "provider_reachable", "provider": "ollama", "ok": false, "reason": "Request timed out after 5 seconds" },
{ "name": "model_available", "model": "llava", "ok": false, "reason": "Model not found on provider" }
]
}
Example response when all prerequisites are satisfied:
{
"ready": true,
"checks": [
{ "name": "provider_reachable", "provider": "ollama", "ok": true },
{ "name": "model_available", "model": "llava", "ok": true }
]
}
Checks to implement (to be refined):
provider_reachable — provider responds within a short timeout
model_available — the requested model exists on the provider
Plugin — call preflight before creating the Activity
Before sending the activity creation request, the plugin calls the preflight endpoint. If ready is false:
- Show an actionable warning dialog listing the failed checks, e.g.:
"Cannot start the activity: Ollama is unreachable. Make sure the Ollama service is running and try again."
- Offer the user the choice to cancel or proceed anyway (in case the check is a false negative or the user has just fixed the problem).
When ready is true, proceed with activity creation as normal.
Notes
This check is intentionally a best-effort snapshot: there is a TOCTOU window between the preflight and the actual activity start. The goal is not to guarantee success, but to give the user an opportunity to detect and fix infrastructure problems before starting. The anomaly detection in activity results (issue #129) remains the fallback for failures that occur during execution.
Acceptance criteria
- API:
POST /api/activities/preflight returns ready: true when all checks pass
- API: returns
ready: false with per-check details when any prerequisite fails
- API:
provider_reachable check uses a short timeout (not the full activity timeout)
- Plugin: calls preflight before creating an Activity
- Plugin: shows an actionable warning dialog when
ready is false
- Plugin: allows the user to proceed anyway or cancel
- Existing activity creation flow is unchanged when preflight passes
Affected components
api/ — new preflight endpoint
plugin/ — activity creation flow
Problem
When the user starts an Activity, failures due to infrastructure problems (e.g., Ollama unreachable, model not available) are only discovered after the activity has run — every photo ends up failed with the same error, and there is no actionable feedback upfront.
The user has no opportunity to fix the problem before wasting time waiting for a doomed activity.
Proposed solution
API — new preflight endpoint
Add a
POST /api/activities/preflightendpoint that accepts the same parameters as activity creation and checks whether all prerequisites are satisfied.Example request:
{ "provider": "ollama", "model": "llava" }Example response when prerequisites are not met:
{ "ready": false, "checks": [ { "name": "provider_reachable", "provider": "ollama", "ok": false, "reason": "Request timed out after 5 seconds" }, { "name": "model_available", "model": "llava", "ok": false, "reason": "Model not found on provider" } ] }Example response when all prerequisites are satisfied:
{ "ready": true, "checks": [ { "name": "provider_reachable", "provider": "ollama", "ok": true }, { "name": "model_available", "model": "llava", "ok": true } ] }Checks to implement (to be refined):
provider_reachable— provider responds within a short timeoutmodel_available— the requested model exists on the providerPlugin — call preflight before creating the Activity
Before sending the activity creation request, the plugin calls the preflight endpoint. If
readyisfalse:"Cannot start the activity: Ollama is unreachable. Make sure the Ollama service is running and try again."
When
readyistrue, proceed with activity creation as normal.Notes
This check is intentionally a best-effort snapshot: there is a TOCTOU window between the preflight and the actual activity start. The goal is not to guarantee success, but to give the user an opportunity to detect and fix infrastructure problems before starting. The anomaly detection in activity results (issue #129) remains the fallback for failures that occur during execution.
Acceptance criteria
POST /api/activities/preflightreturnsready: truewhen all checks passready: falsewith per-check details when any prerequisite failsprovider_reachablecheck uses a short timeout (not the full activity timeout)readyisfalseAffected components
api/— new preflight endpointplugin/— activity creation flow