feat(api): add minimal workflow-runs backend surface for headless automation

[DrHepa]

Summary

I’d like to propose a small, additive backend surface for headless workflow execution in Modly.

The goal is not to introduce generic workflow management or a DAG engine in the API.

The goal is just to expose a minimal execution surface for the most practical automation case:

image -> model -> mesh

Problem

Right now, Modly already has:

• a UI workflow editor
• workflow nodes/extensions
• Electron/renderer-side workflow interactions

But there is no small, stable, headless backend surface for external automation tools.

That makes it hard to build:

• external CLI tooling
• MCP integrations
• agent-driven workflows
• scripting around Modly without going through desktop/UI-only surfaces

Important scope constraint

This proposal is not asking for:

• saved workflow management in the API
• workflow_id
• workflow list/save/import/export
• generic DAG execution
• process-node orchestration over HTTP
• real Add to Scene execution

Add to Scene should remain UI-only.

Proposal

Add a minimal backend family such as:

• POST /workflow-runs/from-image
• GET /workflow-runs/{run_id}
• POST /workflow-runs/{run_id}/cancel

Intended behavior

POST /workflow-runs/from-image

Creates a run for the simple workflow-like case:

• input image
• canonical model_id
• optional params object

Returns something like:

{
  "run_id": "uuid",
  "status": "pending"
}

GET /workflow-runs/{run_id}

Returns the current run state:

{
  "run_id": "uuid",
  "status": "running",
  "progress": 42,
  "step": "Loading model...",
  "output_url": null,
  "error": null,
  "scene_candidate": null
}

or on success:

{
  "run_id": "uuid",
  "status": "done",
  "progress": 100,
  "step": "Completed",
  "output_url": "/workspace/Default/output.glb",
  "error": null,
  "scene_candidate": {
    "workspace_path": "Default/output.glb"
  }
}

POST /workflow-runs/{run_id}/cancel

Requests cancellation using the same job lifecycle already used elsewhere.

Why this is useful

This would enable a clean headless path for:

• automation
• external tools
• CLI wrappers
• MCP integrations
• agent workflows

without exposing the entire workflow editor/runtime model.

Why this stays small

This can be implemented as a thin façade over the existing generation/job-based backend behavior rather than a brand-new execution engine.

That means:

• additive API
• limited scope
• no UI regression risk
• no need to expose stored workflows or Electron IPC internals

Explicit non-goals

This proposal does not try to solve:

• workflow persistence
• workflow editing
• generic node graphs
• process extensions over HTTP
• scene injection / Add to Scene
• desktop-only actions

Why issue first

I’m opening this as a discussion first because it affects product surface and automation strategy, and I’d rather align on scope before sending a PR.

Question

Would you be open to a small PR for this minimal workflow-runs backend surface, explicitly limited to the from-image execution case?

[m13v]

the thin facade approach is the right call. we built a similar headless execution surface for our desktop automation app and the biggest lesson was: expose just the execution endpoint and status polling, nothing else. the temptation to add workflow persistence and node configuration to the API always creeps in but it doubles the maintenance surface.

one pattern that helped us: return a streaming SSE endpoint alongside the polling endpoint for workflow run status. polling works but for agent integrations, agents prefer streaming because they can react to progress updates without wasting requests on empty polls. also consider adding an idempotency key on the POST endpoint. agents sometimes retry requests on timeout and without idempotency you end up with duplicate runs that burn GPU time for nothing.

[m13v]

our tool execution layer that handles dispatch, validation, streaming results, and the multi-turn execution cycle for headless agent workflows: https://github.com/m13v/fazm/blob/main/Desktop/Sources/Providers/ChatToolExecutor.swift