Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Attach uploaded files to agent runs so the run's end deletes them (#8265)
Aaron Perezc2e591982b3a
diff --git a/alembic/versions/2026_08_22_2203-fd23c7ac01d0_add_run_id_to_uploaded_files.py b/alembic/versions/2026_08_22_2203-fd23c7ac01d0_add_run_id_to_uploaded_files.pynew file mode 100644index 000000000..740732abf--- /dev/null+++ b/alembic/versions/2026_08_22_2203-fd23c7ac01d0_add_run_id_to_uploaded_files.py@@ -0,0 +1,37 @@+"""add run_id to uploaded_files++Revision ID: fd23c7ac01d0+Revises: 613e4f756671+Create Date: 2026-08-22T22:03:10.974717+00:00++"""++from typing import Sequence, Union++import sqlalchemy as sa++from alembic import op++# revision identifiers, used by Alembic.+revision: str = "fd23c7ac01d0"+down_revision: Union[str, None] = "613e4f756671"+branch_labels: Union[str, Sequence[str], None] = None+depends_on: Union[str, Sequence[str], None] = None+++def upgrade() -> None:+ op.execute("SET lock_timeout = '5s';")+ op.add_column("uploaded_files", sa.Column("run_id", sa.String(), nullable=True))+ op.create_index(+ "ix_uploaded_files_run_id_live",+ "uploaded_files",+ ["run_id"],+ unique=False,+ postgresql_where=sa.text("deleted_at IS NULL AND run_id IS NOT NULL"),+ )+++def downgrade() -> None:+ op.execute("SET lock_timeout = '5s';")+ op.drop_index("ix_uploaded_files_run_id_live", table_name="uploaded_files")+ op.drop_column("uploaded_files", "run_id")diff --git a/docs/api-reference/openapi.json b/docs/api-reference/openapi.jsonindex 9d09e4f88..1911b912d 100644--- a/docs/api-reference/openapi.json+++ b/docs/api-reference/openapi.json@@ -23827,6 +23827,27 @@"agent","code"]+ },+ "file_ids": {+ "anyOf": [+ {+ "items": {+ "type": "string"+ },+ "type": "array",+ "maxItems": 50+ },+ {+ "type": "null"+ }+ ],+ "title": "File Ids",+ "description": "\nIds of files uploaded through `POST /v1/upload_file` to attach to this run. Skyvern deletes an attached file as soon as the run finishes, so there is nothing to clean up afterwards. Reference an attached file by its id anywhere a file URL is accepted (for example in `parameters` or in the prompt) and no presigned URL is ever created for it. A file can be attached to one run at a time, and must not already be deleted.\n",+ "examples": [+ [+ "file_123456789"+ ]+ ]}},"type": "object",@@ -24147,6 +24168,27 @@"agent","code"]+ },+ "file_ids": {+ "anyOf": [+ {+ "items": {+ "type": "string"+ },+ "type": "array",+ "maxItems": 50+ },+ {+ "type": "null"+ }+ ],+ "title": "File Ids",+ "description": "\nIds of files uploaded through `POST /v1/upload_file` to attach to this run. Skyvern deletes an attached file as soon as the run finishes, so there is nothing to clean up afterwards. Reference an attached file by its id anywhere a file URL is accepted (for example in `parameters` or in the prompt) and no presigned URL is ever created for it. A file can be attached to one run at a time, and must not already be deleted.\n",+ "examples": [+ [+ "file_123456789"+ ]+ ]}},"type": "object",@@ -29726,6 +29768,27 @@],"title": "Run Metadata","description": "String key/value metadata to attach to this workflow run for analytics tag filtering."+ },+ "file_ids": {+ "anyOf": [+ {+ "items": {+ "type": "string"+ },+ "type": "array",+ "maxItems": 50+ },+ {+ "type": "null"+ }+ ],+ "title": "File Ids",+ "description": "\nIds of files uploaded through `POST /v1/upload_file` to attach to this run. Skyvern deletes an attached file as soon as the run finishes, so there is nothing to clean up afterwards. Reference an attached file by its id anywhere a file URL is accepted (for example in `parameters` or in the prompt) and no presigned URL is ever created for it. A file can be attached to one run at a time, and must not already be deleted.\n",+ "examples": [+ [+ "file_123456789"+ ]+ ]}},"type": "object",@@ -29989,6 +30052,27 @@],"title": "Run Metadata","description": "String key/value metadata to attach to this workflow run for analytics tag filtering."+ },+ "file_ids": {+ "anyOf": [+ {+ "items": {+ "type": "string"+ },+ "type": "array",+ "maxItems": 50+ },+ {+ "type": "null"+ }+ ],+ "title": "File Ids",+ "description": "\nIds of files uploaded through `POST /v1/upload_file` to attach to this run. Skyvern deletes an attached file as soon as the run finishes, so there is nothing to clean up afterwards. Reference an attached file by its id anywhere a file URL is accepted (for example in `parameters` or in the prompt) and no presigned URL is ever created for it. A file can be attached to one run at a time, and must not already be deleted.\n",+ "examples": [+ [+ "file_123456789"+ ]+ ]}},"type": "object",diff --git a/skyvern/config.py b/skyvern/config.pyindex ab7312ce9..7dba7a448 100644--- a/skyvern/config.py+++ b/skyvern/config.py@@ -316,6 +316,11 @@ class Settings(BaseSettings):# retention period cannot be used to pin storage indefinitely; omitting retention_days# still means "no expiry of its own", governed by the org's data-retention policy.MAX_UPLOADED_FILE_RETENTION_DAYS: int = Field(default=365, gt=0)+ # Backstop expiry given to a file attached to a run, so a run that never reaches its+ # terminal handler (cancelled worker, lost node) still cannot strand the bytes. Must stay+ # comfortably above WORKFLOW_RUN_MAX_ELAPSED_TIME_MINUTES plus queue time, since deleting+ # a file mid-run would fail the run that is using it.+ RUN_ATTACHED_FILE_BACKSTOP_HOURS: int = Field(default=24, gt=0)AWS_S3_BUCKET_ARTIFACTS: str = "skyvern-artifacts"AWS_S3_BUCKET_SCREENSHOTS: str = "skyvern-screenshots"AWS_S3_BUCKET_BROWSER_SESSIONS: str = "skyvern-browser-sessions"diff --git a/skyvern/forge/agent.py b/skyvern/forge/agent.pyindex 273b59ca4..16db6cd71 100644--- a/skyvern/forge/agent.py+++ b/skyvern/forge/agent.py@@ -160,7 +160,7 @@ from skyvern.forge.validation_evidence_router import ()from skyvern.schemas.runs import CUA_ENGINES, RunEnginefrom skyvern.schemas.steps import AgentStepOutput-from skyvern.services import run_service, service_utils+from skyvern.services import run_service, service_utils, uploaded_file_servicefrom skyvern.services.action_service import get_action_historyfrom skyvern.services.error_detection_service import detect_user_defined_errors_for_taskfrom skyvern.services.otp_service import (@@ -6138,6 +6138,11 @@ class ForgeAgent:apply_context_attrs(_cl_wait_span)await app.ARTIFACT_MANAGER.wait_for_upload_aiotasks([task.task_id])+ # Before the webhook, so a caller acting on the run's completion already sees the+ # attached files gone. Tasks belonging to a workflow run returned above; their+ # attachments hang off the workflow run and are deleted by its own cleanup.+ await uploaded_file_service.delete_files_attached_to_run(run_id=task.task_id)+if need_call_webhook:with traced_span(_tracer, "skyvern.agent.cleanup.webhook") as _cl_wh_span:apply_context_attrs(_cl_wh_span)diff --git a/skyvern/forge/sdk/api/files.py b/skyvern/forge/sdk/api/files.pyindex 6b3c7f5f2..c022c1c71 100644--- a/skyvern/forge/sdk/api/files.py+++ b/skyvern/forge/sdk/api/files.py@@ -45,6 +45,8 @@ from skyvern.forge.sdk.core.http_request_authorization import (RedirectHopAuthorizer,authorize_request_hop_once,)+from skyvern.forge.sdk.db.id import UPLOADED_FILE_PREFIX+from skyvern.services import uploaded_file_servicefrom skyvern.utils.url_validators import (MAX_SAFE_REDIRECTS,SAFE_REDIRECT_STATUS_CODES,@@ -56,6 +58,33 @@ if TYPE_CHECKING:LOG = structlog.get_logger()+_UPLOADED_FILE_ID_PATTERN = re.compile(rf"^{UPLOADED_FILE_PREFIX}_[0-9]+$")+++def is_uploaded_file_id(value: str) -> bool:+ """Whether a value names a file uploaded through ``POST /v1/upload_file``.++ Distinguishable from a URL by construction: an id carries no scheme, and ``file_`` is not+ a parsable URL scheme, so this can never shadow a ``file://`` path.+ """+ return bool(_UPLOADED_FILE_ID_PATTERN.match(value.strip()))+++async def resolve_uploaded_file_id(file_id: str, organization_id: str | None) -> str:+ """Turn a file id into the storage URI holding its bytes.++ The URI comes from the ``uploaded_files`` row rather than from input, and the org scope is+ part of the lookup, so a caller can only ever name their own organization's files.+ """+ if organization_id is None:+ raise PermissionError(f"No permission to access file: {file_id}")+ storage_uri = await uploaded_file_service.resolve_file_reference(+ file_id=file_id.strip(), organization_id=organization_id+ )+ if storage_uri is None:+ raise FileNotFoundError(f"File not found: {file_id}")+ return storage_uri+def get_file_name_and_suffix_from_headers(headers: CIMultiDictProxy[str] | dict[str, str]) -> tuple[str, str]:file_stem = ""@@ -345,6 +374,11 @@ def validate_download_url(url: str, organization_id: str | None = None) -> bool:True if valid, False otherwise."""try:+ # A file id resolves to an org-scoped storage URI at download time, and that URI is+ # re-checked against the org prefix before any bytes are read.+ if is_uploaded_file_id(url):+ return organization_id is not None+parsed_url = urlparse(url)scheme = parsed_url.scheme.lower()@@ -393,6 +427,11 @@ async def download_file(if not url or not url.strip():raise ValueError("Download URL is empty — no file download was triggered by the browser")+ # Resolved before the try below so a missing or cross-org file id fails loudly instead of+ # falling through to the HTTP fetch path with an id as the URL.+ if is_uploaded_file_id(url):+ url = await resolve_uploaded_file_id(url, organization_id)+requested_url = urltry:# Check if URL is a Google Drive linkdiff --git a/skyvern/forge/sdk/db/models.py b/skyvern/forge/sdk/db/models.pyindex dae990c5b..9e5246bf0 100644--- a/skyvern/forge/sdk/db/models.py+++ b/skyvern/forge/sdk/db/models.py@@ -2061,6 +2061,11 @@ class UploadedFileModel(Base):postgresql_where=text("deleted_at IS NULL AND expires_at IS NOT NULL"),),Index("ix_uploaded_files_organization_id", "organization_id"),+ Index(+ "ix_uploaded_files_run_id_live",+ "run_id",+ postgresql_where=text("deleted_at IS NULL AND run_id IS NOT NULL"),+ ),CheckConstraint("size_bytes >= 0", name="ck_uploaded_files_size_bytes_non_negative"),)@@ -2074,6 +2079,10 @@ class UploadedFileModel(Base):# NULL means the file has no caller-specified lifetime and is governed only by the# organization's existing data-retention policy.expires_at = Column(DateTime, nullable=True)+ # The run this file is attached to, deleted when that run reaches a terminal state. No+ # foreign key: a run id is a task id, a workflow run id, or a task v2 id depending on the+ # engine, so there is no single table to point at.+ run_id = Column(String, nullable=True)deleted_at = Column(DateTime, nullable=True)created_at = Column(DateTime, default=datetime.datetime.utcnow, nullable=False)diff --git a/skyvern/forge/sdk/db/repositories/uploaded_files.py b/skyvern/forge/sdk/db/repositories/uploaded_files.pyindex ec0a10752..e2fff08ed 100644--- a/skyvern/forge/sdk/db/repositories/uploaded_files.py+++ b/skyvern/forge/sdk/db/repositories/uploaded_files.py@@ -2,7 +2,7 @@ from __future__ import annotationsfrom datetime import datetime-from sqlalchemy import select, update+from sqlalchemy import func, select, updatefrom skyvern.forge.sdk.db._error_handling import db_operationfrom skyvern.forge.sdk.db.base_repository import BaseRepository@@ -66,6 +66,71 @@ class UploadedFilesRepository(BaseRepository):uploaded_file = result.scalar_one_or_none()return UploadedFile.model_validate(uploaded_file) if uploaded_file else None+ @db_operation("attach_uploaded_files_to_run")+ async def attach_uploaded_files_to_run(+ self,+ file_ids: list[str],+ organization_id: str,+ run_id: str,+ expires_at: datetime,+ ) -> list[UploadedFile]:+ """Bind live files to a run and give them a backstop expiry, returning the rows bound.++ ``expires_at`` is only ever moved earlier. A caller who asked for a shorter+ ``retention_days`` at upload time already has a deletion promise, and attaching to a+ run must not extend the life of their data past it.++ A file already attached to a different run is left alone and omitted from the result,+ so the caller can reject the request rather than silently move an attachment (and with+ it, the deletion trigger) off the run that is still using it.+ """+ now = naive_utc_now()+ async with self.Session() as session:+ result = await session.execute(+ update(UploadedFileModel)+ .where(UploadedFileModel.file_id.in_(file_ids))+ .where(UploadedFileModel.organization_id == organization_id)+ .where(UploadedFileModel.deleted_at.is_(None))+ .where(+ UploadedFileModel.run_id.is_(None) | (UploadedFileModel.run_id == run_id),+ )+ .values(+ run_id=run_id,+ expires_at=func.least(+ func.coalesce(UploadedFileModel.expires_at, to_naive_utc(expires_at)),+ to_naive_utc(expires_at),+ ),+ modified_at=now,+ )+ .returning(UploadedFileModel)+ )+ attached = [UploadedFile.model_validate(row) for row in result.scalars().all()]+ await session.commit()+ return attached++ @db_operation("get_uploaded_files_by_ids")+ async def get_uploaded_files_by_ids(self, file_ids: list[str], organization_id: str) -> list[UploadedFile]:+ async with self.Session() as session:+ stmt = (+ select(UploadedFileModel)+ .where(UploadedFileModel.file_id.in_(file_ids))+ .where(UploadedFileModel.organization_id == organization_id)+ .where(UploadedFileModel.deleted_at.is_(None))+ )+ result = await session.execute(stmt)+ return [UploadedFile.model_validate(row) for row in result.scalars().all()]++ @db_operation("get_uploaded_files_for_run")+ async def get_uploaded_files_for_run(self, run_id: str) -> list[UploadedFile]:+ async with self.Session() as session:+ stmt = (+ select(UploadedFileModel)+ .where(UploadedFileModel.run_id == run_id)+ .where(UploadedFileModel.deleted_at.is_(None))+ )+ result = await session.execute(stmt)+ return [UploadedFile.model_validate(row) for row in result.scalars().all()]+@db_operation("claim_uploaded_file_for_deletion")async def claim_uploaded_file_for_deletion(self, file_id: str, organization_id: str) -> UploadedFile | None:"""Atomically mark a live row deleted and return it, or return None if it wasn't live.diff --git a/skyvern/forge/sdk/routes/agent_protocol.py b/skyvern/forge/sdk/routes/agent_protocol.pyindex 32b16645b..815862285 100644--- a/skyvern/forge/sdk/routes/agent_protocol.py+++ b/skyvern/forge/sdk/routes/agent_protocol.py@@ -268,6 +268,15 @@ class AISuggestionType(str, Enum):DATA_SCHEMA = "data_schema"+async def _assert_files_attachable(file_ids: list[str] | None, organization_id: str) -> None:+ if not file_ids:+ return+ try:+ await uploaded_file_service.assert_files_attachable(file_ids=file_ids, organization_id=organization_id)+ except uploaded_file_service.FileNotAttachable as e:+ raise HTTPException(status_code=422, detail=str(e)) from e++################# /v1 Endpoints #################@base_router.post("/run/tasks",@@ -306,6 +315,7 @@ async def run_task(analytics.capture("skyvern-oss-run-task", data={"url": run_request.url})await PermissionCheckerFactory.get_instance().check(current_org, browser_session_id=run_request.browser_session_id)await app.RATE_LIMITER.rate_limit_submit_run(current_org.organization_id)+ await _assert_files_attachable(run_request.file_ids, current_org.organization_id)skyvern_ctx = skyvern_context.current()# Per-request distinct_id makes the TTLCache effectively single-use here; that's the@@ -413,6 +423,7 @@ async def run_task(x_api_key=x_api_key,request=request,background_tasks=background_tasks,+ file_ids=run_request.file_ids,)except task_v1_service.InvalidTaskV1ModelError as e:raise HTTPException(status_code=400, detail=str(e)) from e@@ -464,6 +475,7 @@ async def run_task(browser_session_id=run_request.browser_session_id,start_fresh_browser=run_request.start_fresh_browser,max_screenshot_scrolls=run_request.max_screenshot_scrolls,+ file_ids=run_request.file_ids,),)if run_request.engine == RunEngine.skyvern_v2:@@ -509,6 +521,15 @@ async def run_task(span.set_attribute("task_v2_id", task_v2.observer_cruise_id)if task_v2.workflow_run_id:span.set_attribute("workflow_run_id", task_v2.workflow_run_id)+ # A task v2 executes as a workflow run, and it is the workflow run's teardown that+ # deletes attachments, so bind to that id rather than the task v2 id this endpoint+ # returns as run_id. Done before dispatch so the run cannot finish before it is bound.+ if task_v2.workflow_run_id:+ await uploaded_file_service.attach_files_to_run(+ file_ids=run_request.file_ids or [],+ organization_id=current_org.organization_id,+ run_id=task_v2.workflow_run_id,+ )await AsyncExecutorFactory.get_executor().execute_task_v2(request=request,background_tasks=background_tasks,@@ -553,6 +574,7 @@ async def run_task(data_extraction_schema=task_v2.extracted_information_schema,publish_workflow=run_request.publish_workflow,max_screenshot_scrolls=run_request.max_screenshot_scrolls,+ file_ids=run_request.file_ids,),)LOG.error("Invalid agent engine", engine=run_request.engine, organization_id=current_org.organization_id)@@ -633,6 +655,7 @@ async def run_workflow(current_org, browser_session_id=workflow_run_request.browser_session_id)await app.RATE_LIMITER.rate_limit_submit_run(current_org.organization_id)+ await _assert_files_attachable(workflow_run_request.file_ids, current_org.organization_id)workflow_id = workflow_run_request.workflow_idcontext = skyvern_context.ensure_context()request_id = context.request_id@@ -656,6 +679,11 @@ async def run_workflow()except MissingBrowserAddressError as e:raise HTTPException(status_code=400, detail=str(e)) from e+ await uploaded_file_service.attach_files_to_run(+ file_ids=workflow_run_request.file_ids or [],+ organization_id=current_org.organization_id,+ run_id=workflow_run.workflow_run_id,+ )background_tasks.add_task(app.AGENT_FUNCTION.on_run_created,organization_id=current_org.organization_id,diff --git a/skyvern/forge/sdk/schemas/files.py b/skyvern/forge/sdk/schemas/files.pyindex d307751bb..5032b6cef 100644--- a/skyvern/forge/sdk/schemas/files.py+++ b/skyvern/forge/sdk/schemas/files.py@@ -33,6 +33,7 @@ class UploadedFile(BaseModel):filename: strsize_bytes: int | None = Noneexpires_at: datetime | None = None+ run_id: str | None = Nonedeleted_at: datetime | None = Nonecreated_at: datetimemodified_at: datetimediff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.pyindex 11a65c913..76ed865bb 100644--- a/skyvern/forge/sdk/workflow/service.py+++ b/skyvern/forge/sdk/workflow/service.py@@ -228,7 +228,7 @@ from skyvern.schemas.workflows import (WorkflowDefinitionYAML,WorkflowStatus,)-from skyvern.services import script_service, workflow_script_service+from skyvern.services import script_service, uploaded_file_service, workflow_script_servicefrom skyvern.services.script_review_cap import (check_and_increment_cap_v3,increment_script_review_counter_v2,@@ -11249,6 +11249,10 @@ class WorkflowService:workflow_run_id=workflow_run.workflow_run_id,)+ # Before the webhook, so a caller acting on the run's completion already sees the+ # attached files gone.+ await uploaded_file_service.delete_files_attached_to_run(run_id=workflow_run.workflow_run_id)+if need_call_webhook:await self.execute_workflow_webhook(workflow_run, api_key)finally:diff --git a/skyvern/schemas/docs/doc_strings.py b/skyvern/schemas/docs/doc_strings.pyindex b9c775c8e..d64f4efe1 100644--- a/skyvern/schemas/docs/doc_strings.py+++ b/skyvern/schemas/docs/doc_strings.py@@ -62,6 +62,10 @@ WEBHOOK_URL_DOC_STRING = """After a run is finished, send an update to this URL. Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq for more details."""+RUN_FILE_IDS_DOC_STRING = """+Ids of files uploaded through `POST /v1/upload_file` to attach to this run. Skyvern deletes an attached file as soon as the run finishes, so there is nothing to clean up afterwards. Reference an attached file by its id anywhere a file URL is accepted (for example in `parameters` or in the prompt) and no presigned URL is ever created for it. A file can be attached to one run at a time, and must not already be deleted.+"""+TOTP_IDENTIFIER_DOC_STRING = """Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://www.skyvern.com/docs/credentials/totp#option-3-push-code-to-skyvern for more details."""diff --git a/skyvern/schemas/runs.py b/skyvern/schemas/runs.pyindex 357c894e9..b73ee4f5d 100644--- a/skyvern/schemas/runs.py+++ b/skyvern/schemas/runs.py@@ -42,6 +42,7 @@ from skyvern.schemas.docs.doc_strings import (MAX_STEPS_DOC_STRING,MODEL_CONFIG,PROXY_LOCATION_DOC_STRING,+ RUN_FILE_IDS_DOC_STRING,TASK_ENGINE_DOC_STRING,TASK_PROMPT_DOC_STRING,TASK_URL_DOC_STRING,@@ -69,6 +70,7 @@ from skyvern.utils.secret_headers import mask_header_valuesfrom skyvern.utils.url_validators import WebhookUrl, validate_browser_host, validate_urlMAX_SEARCH_FETCH_LIMIT = 1000+MAX_RUN_ATTACHED_FILES = 50_BROWSER_ADDRESS_ADAPTER = TypeAdapter(AnyHttpUrl | WebsocketUrl)BROWSER_ADDRESS_SERVER_ASSIGNED_CONTEXT_KEY = "browser_address_is_server_assigned"@@ -224,6 +226,12 @@ class TaskRunRequest(BaseModel):description="Whether to run the task with agent or code. Null means use the default.",examples=["agent", "code"],)+ file_ids: list[str] | None = Field(+ default=None,+ max_length=MAX_RUN_ATTACHED_FILES,+ description=RUN_FILE_IDS_DOC_STRING,+ examples=[["file_123456789"]],+ )@field_validator("run_with", mode="before")@classmethod@@ -397,6 +405,12 @@ class WorkflowRunRequest(BaseModel):default=None,description="String key/value metadata to attach to this workflow run for analytics tag filtering.",)+ file_ids: list[str] | None = Field(+ default=None,+ max_length=MAX_RUN_ATTACHED_FILES,+ description=RUN_FILE_IDS_DOC_STRING,+ examples=[["file_123456789"]],+ )@field_validator("run_with", mode="before")@classmethoddiff --git a/skyvern/services/run_service.py b/skyvern/services/run_service.pyindex e3c3cd788..91a6221f8 100644--- a/skyvern/services/run_service.py+++ b/skyvern/services/run_service.py@@ -21,7 +21,13 @@ from skyvern.schemas.runs import (TaskRunResponse,)from skyvern.schemas.webhooks import RunWebhookReplayResponse-from skyvern.services import task_v1_service, task_v2_service, webhook_service, workflow_service+from skyvern.services import (+ task_v1_service,+ task_v2_service,+ uploaded_file_service,+ webhook_service,+ workflow_service,+)LOG = structlog.get_logger()@@ -123,6 +129,9 @@ async def cancel_task_v1(task_id: str, organization_id: str | None = None, api_kif not task:raise TaskNotFound(task_id=task_id)task = await app.agent.update_task(task, status=TaskStatus.canceled)+ # A cancel short-circuits the run's own teardown, so the attachments are deleted here+ # instead. Same ordering as teardown: bytes gone before the webhook announces the run.+ await uploaded_file_service.delete_files_attached_to_run(run_id=task_id)await app.agent.execute_task_webhook(task=task, api_key=api_key)@@ -133,6 +142,9 @@ async def cancel_task_v2(task_id: str, organization_id: str | None = None) -> Noawait task_v2_service.mark_task_v2_as_canceled(task_v2_id=task_id, workflow_run_id=task_v2.workflow_run_id, organization_id=organization_id)+ # A task v2's attachments are bound to the workflow run it executes as, not to task_id.+ if task_v2.workflow_run_id:+ await uploaded_file_service.delete_files_attached_to_run(run_id=task_v2.workflow_run_id)async def cancel_workflow_run(@@ -160,6 +172,7 @@ async def cancel_workflow_run(continueawait app.WORKFLOW_SERVICE.mark_workflow_run_as_canceled(child_workflow_run.workflow_run_id)await app.WORKFLOW_SERVICE.mark_workflow_run_as_canceled(workflow_run_id)+ await uploaded_file_service.delete_files_attached_to_run(run_id=workflow_run_id)await app.WORKFLOW_SERVICE.execute_workflow_webhook(workflow_run, api_key=api_key)diff --git a/skyvern/services/task_v1_service.py b/skyvern/services/task_v1_service.pyindex 127eaa8d8..b4081de8c 100644--- a/skyvern/services/task_v1_service.py+++ b/skyvern/services/task_v1_service.py@@ -21,6 +21,7 @@ from skyvern.forge.sdk.schemas.organizations import Organizationfrom skyvern.forge.sdk.schemas.task_generations import TaskGeneration, TaskGenerationBasefrom skyvern.forge.sdk.schemas.tasks import Task, TaskRequest, TaskResponse, TaskStatusfrom skyvern.schemas.runs import RunEngine, RunStatus, RunType+from skyvern.services import uploaded_file_servicefrom skyvern.utils.url_validators import validate_fetch_urlLOG = structlog.get_logger()@@ -116,6 +117,7 @@ async def run_task(request: Request | None = None,background_tasks: BackgroundTasks | None = None,ab_routing_eligible: bool = True,+ file_ids: list[str] | None = None,) -> tuple[Task, RunEngine]:await _validate_task_v1_model_for_org(organization, task.model)if task.url:@@ -157,6 +159,12 @@ async def run_task(organization_id=organization.organization_id,task_id=created_task.task_id,)+ # Bound before dispatch so the run cannot reach teardown with nothing attached to delete.+ await uploaded_file_service.attach_files_to_run(+ file_ids=file_ids or [],+ organization_id=organization.organization_id,+ run_id=created_task.task_id,+ )await AsyncExecutorFactory.get_executor().execute_task(request=request,background_tasks=background_tasks,diff --git a/skyvern/services/uploaded_file_service.py b/skyvern/services/uploaded_file_service.pyindex df2c672c3..170fe1094 100644--- a/skyvern/services/uploaded_file_service.py+++ b/skyvern/services/uploaded_file_service.py@@ -24,6 +24,17 @@ class InvalidRetentionPeriod(ValueError):pass+class FileNotAttachable(ValueError):+ """One or more file ids cannot be attached to the run."""++ def __init__(self, file_ids: list[str]) -> None:+ self.file_ids = file_ids+ super().__init__(+ "These file ids are not available to attach — each must name a file uploaded by this "+ f"organization that is not deleted and not already attached to another run: {', '.join(file_ids)}"+ )++def generate_upload_id() -> str:"""Mint a file id before the bytes are written, so it can be embedded in storage_uri.@@ -101,6 +112,129 @@ async def delete_uploaded_file(*, file_id: str, organization_id: str) -> bool:return True+async def assert_files_attachable(*, file_ids: list[str], organization_id: str) -> None:+ """Reject unknown, deleted, or already-attached file ids before a run is created.++ Attaching happens after the run exists, which is too late to answer 4xx. Checking first+ means a bad file id costs the caller nothing instead of leaving a started run holding an+ attachment it never got.+ """+ requested = list(dict.fromkeys(file_ids))+ if not requested:+ return+ live = await app.DATABASE.uploaded_files.get_uploaded_files_by_ids(+ file_ids=requested, organization_id=organization_id+ )+ attachable = {uploaded_file.file_id for uploaded_file in live if uploaded_file.run_id is None}+ unattachable = [file_id for file_id in requested if file_id not in attachable]+ if unattachable:+ raise FileNotAttachable(unattachable)+++async def attach_files_to_run(*, file_ids: list[str], organization_id: str, run_id: str) -> list[UploadedFile]:+ """Bind uploaded files to a run so the run's terminal handler deletes them.++ Every attachment also gets a backstop expiry: the terminal handler is the fast path, and+ the existing expiry sweep is what guarantees the bytes go away even if a run never reaches+ it. Without the backstop, a lost worker would strand exactly the sensitive data this+ feature exists to bound.+ """+ if not file_ids:+ return []++ backstop = datetime.now(timezone.utc) + timedelta(hours=settings.RUN_ATTACHED_FILE_BACKSTOP_HOURS)+ attached = await app.DATABASE.uploaded_files.attach_uploaded_files_to_run(+ file_ids=list(dict.fromkeys(file_ids)),+ organization_id=organization_id,+ run_id=run_id,+ expires_at=backstop,+ )+ attached_ids = {uploaded_file.file_id for uploaded_file in attached}+ missed = [file_id for file_id in dict.fromkeys(file_ids) if file_id not in attached_ids]+ if missed:+ # Lost a race with a concurrent delete or another run's attach between the pre-check+ # and here. The run is already created, so this is logged rather than raised: the run+ # proceeds and simply has no attachment to delete for those ids.+ LOG.warning(+ "Some files could not be attached to the run",+ organization_id=organization_id,+ run_id=run_id,+ file_ids=missed,+ )+ if attached:+ LOG.info(+ "Attached uploaded files to run",+ organization_id=organization_id,+ run_id=run_id,+ file_ids=sorted(attached_ids),+ backstop_expires_at=backstop,+ )+ return attached+++async def delete_files_attached_to_run(*, run_id: str) -> int:+ """Delete every file attached to a run. Safe to call for runs that have no attachments.++ Never raises. This runs inside run teardown, where an exception would cost the run its+ webhook and artifact persistence — a far worse outcome than a late delete. Anything that+ fails here is picked up by the expiry sweep via the backstop expiry set at attach time.+ """+ try:+ attached = await app.DATABASE.uploaded_files.get_uploaded_files_for_run(run_id=run_id)+ except Exception:+ LOG.exception("Failed to look up files attached to run", run_id=run_id)+ return 0+ if not attached:+ return 0++ deleted = 0+ for uploaded_file in attached:+ try:+ await _delete_stored_object(uploaded_file)+ except Exception:+ LOG.exception(+ "Failed to delete file attached to run",+ organization_id=uploaded_file.organization_id,+ run_id=run_id,+ file_id=uploaded_file.file_id,+ )+ continue+ try:+ await app.DATABASE.uploaded_files.claim_uploaded_file_for_deletion(+ file_id=uploaded_file.file_id, organization_id=uploaded_file.organization_id+ )+ except Exception:+ LOG.exception(+ "Deleted the bytes of a run attachment but failed to retire its row",+ organization_id=uploaded_file.organization_id,+ run_id=run_id,+ file_id=uploaded_file.file_id,+ )+ continue+ deleted += 1++ LOG.info(+ "Deleted files attached to run",+ run_id=run_id,+ attached=len(attached),+ deleted=deleted,+ )+ return deleted+++async def resolve_file_reference(*, file_id: str, organization_id: str) -> str | None:+ """Return the storage URI behind a file id, or None when the org has no such live file.++ This is what lets a caller hand the agent a file id instead of a presigned URL: the URI is+ read from the row rather than taken from input, and the storage layer re-checks it against+ the organization's prefix before any bytes are read.+ """+ uploaded_file = await app.DATABASE.uploaded_files.get_uploaded_file(+ file_id=file_id, organization_id=organization_id+ )+ return uploaded_file.storage_uri if uploaded_file else None++async def purge_expired_files(*, limit: int = 500) -> dict[str, int]:"""Delete files whose caller-specified retention period has elapsed.diff --git a/tests/unit/test_uploaded_file_retention.py b/tests/unit/test_uploaded_file_retention.pyindex 574b1c89d..339a57738 100644--- a/tests/unit/test_uploaded_file_retention.py+++ b/tests/unit/test_uploaded_file_retention.py@@ -20,10 +20,12 @@ from fastapi import FastAPIfrom fastapi.testclient import TestClientfrom skyvern.config import settings+from skyvern.forge.sdk.api import files as files_apifrom skyvern.forge.sdk.artifact.storage.s3 import S3Storagefrom skyvern.forge.sdk.routes.routers import base_routerfrom skyvern.forge.sdk.schemas.files import UploadedFilefrom skyvern.forge.sdk.schemas.organizations import Organization+from skyvern.schemas.runs import RunEnginefrom skyvern.services import uploaded_file_serviceVICTIM_ORG_ID = "o_victim"@@ -41,7 +43,13 @@ class FakeUploadedFilesRepository:self.rows: dict[str, UploadedFile] = {}self._next_id = 0- def seed(self, organization_id: str, expires_at: datetime | None = None, filename: str = "secret.pdf") -> str:+ def seed(+ self,+ organization_id: str,+ expires_at: datetime | None = None,+ filename: str = "secret.pdf",+ run_id: str | None = None,+ ) -> str:self._next_id += 1file_id = f"file_{self._next_id}"now = datetime.now(timezone.utc)@@ -51,6 +59,7 @@ class FakeUploadedFilesRepository:storage_uri=_uri(organization_id, filename),filename=filename,expires_at=expires_at,+ run_id=run_id,created_at=now,modified_at=now,)@@ -104,6 +113,37 @@ class FakeUploadedFilesRepository:if row.deleted_at is None and row.expires_at is not None and row.expires_at <= before][:limit]+ async def get_uploaded_files_by_ids(self, file_ids: list[str], organization_id: str) -> list[UploadedFile]:+ return [+ row+ for file_id in file_ids+ if (row := self.rows.get(file_id)) is not None+ and row.organization_id == organization_id+ and row.deleted_at is None+ ]++ async def get_uploaded_files_for_run(self, run_id: str) -> list[UploadedFile]:+ return [row for row in self.rows.values() if row.run_id == run_id and row.deleted_at is None]++ async def attach_uploaded_files_to_run(+ self,+ file_ids: list[str],+ organization_id: str,+ run_id: str,+ expires_at: datetime,+ ) -> list[UploadedFile]:+ attached = []+ for file_id in file_ids:+ row = self.rows.get(file_id)+ if row is None or row.organization_id != organization_id or row.deleted_at is not None:+ continue+ if row.run_id is not None and row.run_id != run_id:+ continue+ row.run_id = run_id+ row.expires_at = min(row.expires_at, expires_at) if row.expires_at else expires_at+ attached.append(row)+ return attached+class FakeStorage:"""Enforces the same org-prefix rule the real storage backends do."""@@ -351,6 +391,145 @@ class TestExpirySweep:assert repo.live_ids() == {file_id}+class TestRunAttachment:+ """Attaching a file to a run (SKY-14439): the run's end is what deletes it."""++ @pytest.mark.asyncio+ async def test_a_runs_attached_files_are_deleted_when_the_run_ends(+ self, service_app: object, repo: FakeUploadedFilesRepository, storage: FakeStorage+ ) -> None:+ attached = repo.seed(VICTIM_ORG_ID, filename="cv.pdf")+ other_run = repo.seed(VICTIM_ORG_ID, filename="other.pdf", run_id="wr_other")+ unattached = repo.seed(VICTIM_ORG_ID, filename="kept.pdf")+ await uploaded_file_service.attach_files_to_run(+ file_ids=[attached], organization_id=VICTIM_ORG_ID, run_id="wr_1"+ )++ deleted = await uploaded_file_service.delete_files_attached_to_run(run_id="wr_1")++ assert deleted == 1+ assert storage.deleted == [_uri(VICTIM_ORG_ID, "cv.pdf")]+ assert repo.live_ids() == {other_run, unattached}++ @pytest.mark.asyncio+ async def test_an_attached_file_gets_a_backstop_expiry(+ self, service_app: object, repo: FakeUploadedFilesRepository+ ) -> None:+ """A run that never reaches its terminal handler must not strand the bytes forever."""+ file_id = repo.seed(VICTIM_ORG_ID, expires_at=None)++ await uploaded_file_service.attach_files_to_run(+ file_ids=[file_id], organization_id=VICTIM_ORG_ID, run_id="wr_1"+ )++ expires_at = repo.rows[file_id].expires_at+ assert expires_at is not None+ assert expires_at <= datetime.now(timezone.utc) + timedelta(hours=settings.RUN_ATTACHED_FILE_BACKSTOP_HOURS)++ @pytest.mark.asyncio+ @pytest.mark.parametrize("attach_to_other_run", [True, False])+ async def test_a_file_another_run_is_using_cannot_be_attached(+ self, service_app: object, repo: FakeUploadedFilesRepository, attach_to_other_run: bool+ ) -> None:+ """Re-attaching would move the deletion trigger onto a run the first one is still using."""+ file_id = repo.seed(VICTIM_ORG_ID, run_id="wr_first" if attach_to_other_run else None)++ if attach_to_other_run:+ with pytest.raises(uploaded_file_service.FileNotAttachable):+ await uploaded_file_service.assert_files_attachable(file_ids=[file_id], organization_id=VICTIM_ORG_ID)+ else:+ await uploaded_file_service.assert_files_attachable(file_ids=[file_id], organization_id=VICTIM_ORG_ID)++ @pytest.mark.asyncio+ async def test_another_orgs_file_is_not_attachable(+ self, service_app: object, repo: FakeUploadedFilesRepository+ ) -> None:+ victim_file = repo.seed(VICTIM_ORG_ID)++ with pytest.raises(uploaded_file_service.FileNotAttachable):+ await uploaded_file_service.assert_files_attachable(file_ids=[victim_file], organization_id=ATTACKER_ORG_ID)++ @pytest.mark.asyncio+ async def test_a_task_v1_file_is_bound_before_the_run_is_dispatched(+ self, service_app: object, repo: FakeUploadedFilesRepository, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ """Binding after dispatch would let a fast run reach teardown with nothing to delete."""+ from skyvern.forge.sdk.schemas.tasks import TaskRequest+ from skyvern.services import task_v1_service++ file_id = repo.seed(VICTIM_ORG_ID)+ bound_at_dispatch: list[str | None] = []++ async def execute_task(**kwargs: object) -> None:+ bound_at_dispatch.append(repo.rows[file_id].run_id)++ monkeypatch.setattr(task_v1_service, "_validate_task_v1_model_for_org", AsyncMock())+ monkeypatch.setattr(task_v1_service, "validate_fetch_url", lambda url: url)+ monkeypatch.setattr(+ task_v1_service.app.agent, "create_task", AsyncMock(return_value=SimpleNamespace(task_id="tsk_1"))+ )+ monkeypatch.setattr(+ task_v1_service.app.AGENT_FUNCTION, "resolve_run_engine", AsyncMock(return_value=RunEngine.skyvern_v1)+ )+ monkeypatch.setattr(task_v1_service.app.DATABASE.tasks, "create_task_run", AsyncMock())+ monkeypatch.setattr(+ task_v1_service.AsyncExecutorFactory, "get_executor", lambda: SimpleNamespace(execute_task=execute_task)+ )++ await task_v1_service.run_task(+ TaskRequest(url="https://task.example.test"), _make_org(VICTIM_ORG_ID), file_ids=[file_id]+ )++ assert bound_at_dispatch == ["tsk_1"]++ @pytest.mark.asyncio+ async def test_teardown_deletion_does_not_raise_when_storage_fails(+ self, service_app: object, repo: FakeUploadedFilesRepository, storage: FakeStorage+ ) -> None:+ """An exception here would cost the run its webhook; the sweep retries via the backstop."""+ file_id = repo.seed(VICTIM_ORG_ID, run_id="wr_1")+ storage.fail_with = RuntimeError("s3 is down")++ assert await uploaded_file_service.delete_files_attached_to_run(run_id="wr_1") == 0+ assert repo.live_ids() == {file_id}+++class TestFileIdAsFileReference:+ """A file id can stand in for a URL, so the run never needs a presigned URL."""++ @pytest.mark.parametrize(+ ("value", "expected"),+ [+ ("file_384430212391591428", True),+ ("file:///etc/passwd", False),+ ("https://example.com/cv.pdf", False),+ ("file_", False),+ ],+ )+ def test_only_a_file_id_is_treated_as_one(self, value: str, expected: bool) -> None:+ assert files_api.is_uploaded_file_id(value) is expected++ @pytest.mark.asyncio+ async def test_a_file_id_resolves_to_its_own_orgs_uri_and_no_one_elses(+ self, service_app: object, repo: FakeUploadedFilesRepository+ ) -> None:+ file_id = repo.seed(VICTIM_ORG_ID, filename="cv.pdf")++ assert await files_api.resolve_uploaded_file_id(file_id, VICTIM_ORG_ID) == _uri(VICTIM_ORG_ID, "cv.pdf")+ with pytest.raises(FileNotFoundError):+ await files_api.resolve_uploaded_file_id(file_id, ATTACKER_ORG_ID)++ @pytest.mark.asyncio+ async def test_a_file_id_without_an_organization_is_refused(+ self, service_app: object, repo: FakeUploadedFilesRepository+ ) -> None:+ """Unauthenticated call sites must fail closed rather than resolve someone's file."""+ file_id = repo.seed(VICTIM_ORG_ID)++ with pytest.raises(PermissionError):+ await files_api.resolve_uploaded_file_id(file_id, None)++class TestStorageGuard:"""The real backends' org-prefix check, not a stub of it.