[REFACTOR] Centralize local artifact and task route handling

[lzx1413]

Introduce a local ArtifactStore and route output path validation, upload handling, task submission, wait, cancel, and output responses through shared service helpers.

Keep public API paths intact while reducing duplicated Task/OpenAI/File route behavior and preserving explicit local-only artifact semantics.

Includes focused service and OpenAI route tests for the centralized paths.

Description

Introduce a local-only artifact store and shared service helpers for artifact/output path handling, uploads, task submission, waiting, cancellation, and output responses across Task, OpenAI, and File routes.

Motivation

Task, OpenAI-compatible, and File routes previously duplicated task lifecycle and artifact/output handling logic. Centralizing these paths makes behavior consistent across public APIs, reduces maintenance cost, and keeps local artifact semantics explicit and enforceable.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Performance improvement
• Code refactoring
• Documentation update
• Other (please describe):

Changes Made

• Added local ArtifactStore support for task-scoped outputs, artifact IDs, metadata, cleanup, and local-only backend validation.
• Centralized output path validation, upload handling, task submission, wait, cancel, and output response logic through shared service helpers.
• Refactored Task/OpenAI/File route handlers to use the shared paths while preserving existing public API endpoints.
• Added focused service/OpenAI tests for centralized artifact, task, upload, cancel, and response behavior.
• Updated service documentation and related examples/config coverage.

Testing

• Focused unit/integration tests pass
• Pre-commit lint/format checks pass
• Full pytest tests/ completed
• Benchmarks added/updated (if applicable)

Test commands:

pytest tests/unit/service/test_artifact_store.py tests/unit/service/test_task_application_service.py tests/unit/service/test_task_routes.py tests/unit/openai/test_image_routes.py tests/unit/openai/test_video_routes.py tests/unit/service/test_config.py tests/server/test_middleware.py tests/integration/test_service_api.py tests/unit/service/test_service_refactor_phase0.py
pre-commit run --all-files

Results:

121 passed, 2 skipped
ruff Passed
ruff-format Passed

Note: full pytest tests/ was attempted, but stalled at tests/integration/test_pp_forward_consistency.py::test_pp_forward_vs_no_pp and was manually terminated.

Checklist

• Code follows the project's coding standards (ruff)
• Pre-commit hooks pass (pre-commit run --all-files)
• All tests pass (pytest tests/)
• New tests added for new functionality
• Documentation updated (README, CLAUDE.md, docstrings)
• Commit messages are clear and descriptive
• PR title follows the convention: [TYPE] Brief description

Related Issues

Fixes #

Additional Notes

Artifact storage remains explicitly local-only in this PR. Non-local artifact backends are rejected until implemented intentionally.

GPU Architecture Support

• SM80 (Ampere, Ada Lovelace)
• SM90 (Hopper H100)
• SM100+ (Blackwell)

Performance Impact

No expected inference performance impact. This is a service-layer refactor focused on shared task and artifact handling.

[Copilot]

Pull request overview

This PR refactors the TeleFuser service layer to centralize task lifecycle and local-only artifact handling behind shared helpers, reducing duplicated logic across Task, File, and OpenAI-compatible routes while keeping the public endpoint surface intact.

Changes:

• Introduces ArtifactStore + extended FileService APIs for task-scoped outputs, local artifact IDs/metadata, upload/download safety, and retention/capacity cleanup.
• Adds TaskApplicationService as the canonical route-facing task submission/wait/cancel/output-response path and refactors Task/OpenAI/File routes to use it.
• Improves service/middleware/stream behaviors (readiness endpoint, rate-limit config, WebRTC close reasons/logging) and adds/updates focused unit + integration tests and docs.

Reviewed changes

Copilot reviewed 55 out of 55 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/unit/service/test_task_runtime.py	Adds coverage for artifact-cleanup snapshot split (active vs terminal).
tests/unit/service/test_task_routes.py	Adds multipart form forwarding/upload tests wired through centralized services.
tests/unit/service/test_task_application_service.py	New tests for canonical task submission, output handling, waiting, and cancel paths.
tests/unit/service/test_service_smoke.py	New smoke tests covering task create/status + artifact-id download and OpenAI retrieve metadata.
tests/unit/service/test_service_routes.py	New tests for route profiles, readiness/health, CLI flags, and injected config behavior.
tests/unit/service/test_security_validator.py	Tests updated sandbox wording/semantics (restricted-load validation).
tests/unit/service/test_latent_cache_cli.py	Updates CLI expectations (TaskType + security/skip-validation forwarding).
tests/unit/service/test_config.py	Adds coverage for new artifact + forwarded-for config options and container behaviors.
tests/unit/service/test_artifact_store.py	New tests for local artifact store paths, ids, metadata, cleanup policies, and FileService integration.
tests/unit/openai/test_video_routes.py	Refactors tests to use ASGI transport + centralized task/output handling.
tests/unit/openai/test_integration_server.py	Switches to ASGI transport client for stability.
tests/unit/openai/test_image_routes.py	Refactors tests to use ASGI transport + centralized task/output handling.
tests/unit/openai/_asgi_test_client.py	Adds small httpx ASGI test client wrapper.
tests/server/test_middleware.py	Refactors middleware tests to dispatch directly; adds forwarded-for trust coverage.
tests/integration/test_service_api.py	Adds integration coverage for dynamic multipart form field forwarding.
telefuser/service/webrtc/track.py	Returns drop/accept signals for queued frames/audio; improves logging on termination/cancel.
telefuser/service/webrtc/session_manager.py	Adds close reasons, safer callback handling, improved close logging, and pipeline notify toggle.
telefuser/service/webrtc/chunk_router.py	Adds warnings for decode/send failures instead of silent ignores.
telefuser/service/security/security_validator.py	Clarifies SANDBOX semantics and error messages as restricted-load validation.
telefuser/service/main.py	Uses container config consistently; forwards security-level + skip-validation into server runners.
telefuser/service/core/task_service.py	Routes output-path resolution through task-scoped FileService.get_output_path(..., task_id=...).
telefuser/service/core/task_manager.py	Unifies TaskStatus enum; adds artifact cleanup snapshot API for cleanup loop.
telefuser/service/core/stream_pipeline_service.py	Accepts injected config; routes validation behavior through PipelineValidationConfig.
telefuser/service/core/replica_worker.py	Passes serialized ServerConfig into replica PipelineService initialization.
telefuser/service/core/pipeline_service.py	Accepts injected config; routes validation behavior through PipelineValidationConfig; uses configured task_timeout.
telefuser/service/core/pipeline_pool.py	Serializes config for replica workers.
telefuser/service/core/pipeline_loader.py	Introduces PipelineValidationConfig and removes reliance on global server_config.
telefuser/service/core/file_service.py	Adds artifact store integration, safe streaming downloads/uploads, artifact metadata/id helpers, and cleanup API.
telefuser/service/core/container.py	Enforces local-only artifact backend; initializes FileService with artifact lifecycle config; sets route profiles.
telefuser/service/core/config.py	Adds artifact lifecycle + forwarded-for trust configuration and rate-limit path defaults.
telefuser/service/core/artifact_store.py	New local path-safe artifact store with ids/metadata + retention/capacity cleanup.
telefuser/service/api/task_application_service.py	New canonical helper for submit/wait/cancel/output response/metadata/upload paths.
telefuser/service/api/routers/webrtc.py	Uses ApiServer config for ICE settings; session delete uses session manager ownership.
telefuser/service/api/routers/tasks.py	Refactors task create/form/cancel through TaskApplicationService; supports dynamic multipart form parameters.
telefuser/service/api/routers/stream.py	Improves close logging; closes WebRTC with reason and no pipeline notify.
telefuser/service/api/routers/service.py	Adds readiness endpoint and readiness status propagation; safer pool-status detection.
telefuser/service/api/routers/files.py	Uses FileService.resolve_output_file with 403 on disallowed paths.
telefuser/service/api/openai/video_routes.py	Centralizes task submit/cancel/output response + adds artifact metadata in responses.
telefuser/service/api/openai/protocol.py	Extends OpenAI response schemas with artifact id + metadata fields.
telefuser/service/api/openai/image_routes.py	Centralizes task submit/wait/output response + includes artifact metadata in responses.
telefuser/service/api/openai/adapter.py	Emits artifact id/metadata in image/video responses; adds helper for task-derived video responses.
telefuser/service/api/middleware.py	Moves middleware config off global settings; adds forwarded-for trust option and config injection.
telefuser/service/api/api_server.py	Adds route profiles, TaskApplicationService + artifact cleanup loop, config injection, and safer file streaming.
telefuser/service_types.py	Adds STREAMING to shared TaskStatus enum.
telefuser/entrypoints/cli/main.py	Forwards security_level and skip_validation to service runners.
examples/wan_video/wan22_14b_image_to_video_lora_h100.py	Updates run_with_file signature to accept first_image_path and validate it.
examples/wan_video/wan22_14b_image_to_video_distill_h100.py	Updates run_with_file signature to accept first_image_path and validate it.
examples/wan_video/wan22_14b_image_to_video_distill_fp8_h100.py	Updates run_with_file signature to accept first_image_path and validate it.
examples/wan_video/wan21_14b_image_to_video_lora_h100.py	Updates run_with_file signature to accept first_image_path and validate it.
examples/wan_video/wan21_14b_image_to_video_h100.py	Updates run_with_file signature to accept first_image_path and validate it.
examples/wan_video/async_wan22_14b_image_to_video_distill_h100.py	Updates async run_with_file to accept first_image_path and validate it.
docs/zh/stream_server.md	Documents stream-only app route surface + sandbox semantics and improved session close behavior.
docs/zh/service.md	Documents artifact store semantics/cleanup/config and forwarded-for trust; updates examples.
docs/en/stream_server.md	Documents stream-only app route surface + sandbox semantics and improved session close behavior.
docs/en/service.md	Documents artifact store semantics/cleanup/config and forwarded-for trust; updates examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.