server: flattened handler metadata in responses, shared OpenAPI components, and test updates

[zhaotai]

Summary

• Add and surface flattened runtime handler metadata across server endpoints (no new endpoints).
• Replace per-endpoint, hand-built dicts with a single source to_dict() on the server-side wrapper.
• Consolidate OpenAPI schemas via shared components to remove duplication.
• Update tests to reflect expected behavioral changes.

API changes (intentional)

• Flattened metadata fields are now included in these responses:
  • POST /workflows/{name}/run (200)
  • POST /workflows/{name}/run-nowait (200)
  • GET /results/{handler_id} (200, 202)
  • GET /handlers (200, each item)
• Run-nowait response:
  • status was previously “started”; it now returns status: "running".
• Get result error response:
  • GET /results/{handler_id} now returns a detailed error as text/plain on 500 (instead of a JSON object).

Implementation details

• Introduced server-side wrapper _WorkflowHandler.to_dict() returning a typed HandlerDict.
• Safe accessors on _WorkflowHandler:
  • status: guards unfinished futures and maps to "running" | "completed" | "failed".
  • error: None when unfinished, stringified exception when failed.
  • result: None when unfinished; returns final result when completed.
• Centralized response construction to avoid ad-hoc dict assembly.
• OpenAPI:
  • Added shared components:
    • components.schemas.Handler: flattened, reusable handler response shape.
    • components.schemas.HandlersList: { handlers: Handler[] }.
  • Endpoint docstrings now reference $ref to the above, removing duplication.

Backward compatibility notes

• Run-nowait clients should expect "status": "running" instead of "started".
• Consumers of GET /results/{handler_id} on error (500) should parse a text/plain body (detailed error message) rather than a JSON object.

Testing

• Updated server tests to reflect the above behavioral changes.
• All server tests passing: 72 passed locally.

Migration/Deployment

• No persistence or schema migrations needed.
• No new configuration flags introduced.

[coveralls]

Pull Request Test Coverage Report for Build 17960965298

Details

• 11 of 11 (100.0%) changed or added relevant lines in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-0.01%) to 90.106%

---

Totals
Change from base Build 17960904376:	-0.01%
Covered Lines:	1530
Relevant Lines:	1698

---

💛 - Coveralls