Skip to content

Add pre-flight prerequisites check before starting an Activity #130

Description

@siculo

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:

  1. 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."
  2. 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

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions