Skip to content

Automate browser based workflows with AI

fix(SKY-10255): make block title editable from the right settings sidebar (#6443)

Aaron Perezbf6c09c1f24e
diff --git a/pyproject.toml b/pyproject.toml
index 50b35fba3..7186ef7c2 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -26,6 +26,7 @@ dependencies = [
# browser-only runtime until local stops importing Forge internals.
local = [
"azure-storage-blob>=12.26.0",
+ "google-cloud-storage>=2.18,<4",
"openai>=1.68.2",
"yutori>=0.5.0",
"sqlalchemy>=2.0.29,<3",
@@ -87,6 +88,7 @@ local = [
# with local until the embedded runtime is separated from Forge/server internals.
server = [
"azure-storage-blob>=12.26.0",
+ "google-cloud-storage>=2.18,<4",
"openai>=1.68.2",
"yutori>=0.5.0",
# Plain pip sees LiteLLM's exact openai pin and therefore resolves this
diff --git a/skyvern-frontend/src/routes/workflows/editor/panels/BlockConfigForm.test.tsx b/skyvern-frontend/src/routes/workflows/editor/panels/BlockConfigForm.test.tsx
index 1dbbbdd1e..02f1035cc 100644
--- a/skyvern-frontend/src/routes/workflows/editor/panels/BlockConfigForm.test.tsx
+++ b/skyvern-frontend/src/routes/workflows/editor/panels/BlockConfigForm.test.tsx
@@ -21,6 +21,26 @@ vi.mock("@xyflow/react", async () => {
};
});
+// The sidebar header now renders an editable title for block nodes, which
+// pulls in the label-change hook (needs a ReactFlow store). Stub it so these
+// commit-orchestration tests stay scoped to the body, not the title. The
+// title also needs ResizeObserver (absent in jsdom); that is stubbed per-test
+// in beforeEach/afterEach below to avoid leaking the global across files.
+vi.mock("@/routes/workflows/hooks/useLabelChangeHandler", () => ({
+ useNodeLabelChangeHandler: ({
+ initialValue,
+ }: {
+ id: string;
+ initialValue: string;
+ }) => [initialValue, () => {}] as const,
+}));
+
+class ResizeObserverStub {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
import { useWorkflowPanelStore } from "@/store/WorkflowPanelStore";
import { usePendingCommitsStore } from "@/store/PendingCommitsStore";
@@ -36,12 +56,14 @@ const BLOCK_FORM_KEYS = Object.keys(BLOCK_FORMS) as WorkflowBlockNodeType[];
const ORIGINAL_BLOCK_FORMS = { ...BLOCK_FORMS };
beforeEach(() => {
+ vi.stubGlobal("ResizeObserver", ResizeObserverStub);
mockNodeFixtures.clear();
usePendingCommitsStore.setState({ commits: {} });
useWorkflowPanelStore.getState().setSelectedBlockId(null);
});
afterEach(() => {
+ vi.unstubAllGlobals();
cleanup();
for (const key of BLOCK_FORM_KEYS) {
BLOCK_FORMS[key] = ORIGINAL_BLOCK_FORMS[key];
diff --git a/skyvern-frontend/src/routes/workflows/editor/panels/BlockConfigSidebar.test.tsx b/skyvern-frontend/src/routes/workflows/editor/panels/BlockConfigSidebar.test.tsx
index 9027ff7f1..dc782fd49 100644
--- a/skyvern-frontend/src/routes/workflows/editor/panels/BlockConfigSidebar.test.tsx
+++ b/skyvern-frontend/src/routes/workflows/editor/panels/BlockConfigSidebar.test.tsx
@@ -1,6 +1,12 @@
// @vitest-environment jsdom
-import { act, cleanup, render, screen } from "@testing-library/react";
+import {
+ act,
+ cleanup,
+ fireEvent,
+ render,
+ screen,
+} from "@testing-library/react";
import type { ComponentType } from "react";
import { MemoryRouter } from "react-router-dom";
import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
@@ -22,6 +28,22 @@ vi.mock("../nodes/types", () => ({
workflowBlockTitle: { task: "Task" },
}));
+// The sidebar title delegates label edits to the same hook the canvas tile
+// uses. Stub it so this test pins the wiring (title → handler) without
+// pulling in React Flow node mutation, the parameters store, or the
+// collapse store the real hook depends on.
+const { mockLabelChangeHandler } = vi.hoisted(() => ({
+ mockLabelChangeHandler: vi.fn(),
+}));
+vi.mock("@/routes/workflows/hooks/useLabelChangeHandler", () => ({
+ useNodeLabelChangeHandler: ({
+ initialValue,
+ }: {
+ id: string;
+ initialValue: string;
+ }) => [initialValue, mockLabelChangeHandler] as const,
+}));
+
// `useReactFlow` requires a `<ReactFlowProvider>` ancestor with mounted
// nodes; spinning that up just to read `.getNode(id)` is overkill for a
// structural mount test. Stub it to a deterministic node lookup so
@@ -32,8 +54,18 @@ vi.mock("@xyflow/react", async () => {
await vi.importActual<typeof import("@xyflow/react")>("@xyflow/react");
const nodeFor = (id: string) => ({
id,
- type: "task",
- data: { label: id === "block-a" ? "Alpha" : "Beta" },
+ type: id === "start-block" ? "start" : "task",
+ data: {
+ label:
+ id === "block-a"
+ ? "Alpha"
+ : id === "start-block"
+ ? "__start_block__"
+ : id === "block-readonly"
+ ? "ReadOnly"
+ : "Beta",
+ editable: id !== "block-readonly",
+ },
});
return {
...actual,
@@ -50,6 +82,15 @@ import { useWorkflowPanelStore } from "@/store/WorkflowPanelStore";
import { BLOCK_FORMS, type WorkflowBlockNodeType } from "./BlockConfigForm";
import { BlockConfigSidebar } from "./BlockConfigSidebar";
+// EditableNodeTitle (used by the editable block title) measures truncation
+// via ResizeObserver, which jsdom does not implement. Stubbed per-test in
+// beforeEach/afterEach so the global does not leak across test files.
+class ResizeObserverStub {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
// The structural invariants this file pins are about the sidebar shell,
// not the body content. Stub each entry to a marker component so per-form
// tests handle routing.
@@ -69,6 +110,7 @@ const StubFormForBlockType: (
};
beforeEach(() => {
+ vi.stubGlobal("ResizeObserver", ResizeObserverStub);
useWorkflowPanelStore.getState().setSelectedBlockId(null);
for (const key of BLOCK_FORM_KEYS) {
BLOCK_FORMS[key] = StubFormForBlockType(key);
@@ -76,6 +118,7 @@ beforeEach(() => {
});
afterEach(() => {
+ vi.unstubAllGlobals();
cleanup();
for (const key of BLOCK_FORM_KEYS) {
BLOCK_FORMS[key] = ORIGINAL_BLOCK_FORMS[key];
@@ -218,3 +261,63 @@ describe("BlockConfigSidebar mode gating (SKY-9361)", () => {
expect(screen.getByTestId("block-config-sidebar")).toBeDefined();
});
});
+
+describe("BlockConfigSidebar block title editing (SKY-10255)", () => {
+ beforeEach(() => {
+ mockLabelChangeHandler.mockClear();
+ });
+
+ test("clicking the block title reveals an input and committing a new value calls the label change handler", () => {
+ act(() => {
+ useWorkflowPanelStore.getState().setSelectedBlockId("block-a");
+ });
+ render(
+ <MemoryRouter initialEntries={["/workflows/wpid_abc/edit"]}>
+ <BlockConfigSidebar />
+ </MemoryRouter>,
+ );
+
+ const title = screen.getByText("Alpha");
+ fireEvent.click(title);
+
+ const input = screen.getByRole("textbox");
+ fireEvent.change(input, { target: { value: "renamed_block" } });
+ fireEvent.blur(input);
+
+ expect(mockLabelChangeHandler).toHaveBeenCalledWith("renamed_block");
+ });
+
+ test("keeps the start node title non-editable (no input on click)", () => {
+ act(() => {
+ useWorkflowPanelStore.getState().setSelectedBlockId("start-block");
+ });
+ render(
+ <MemoryRouter initialEntries={["/workflows/wpid_abc/edit"]}>
+ <BlockConfigSidebar />
+ </MemoryRouter>,
+ );
+
+ const title = screen.getByText("Agent Settings");
+ fireEvent.click(title);
+
+ expect(screen.queryByRole("textbox")).toBeNull();
+ expect(mockLabelChangeHandler).not.toHaveBeenCalled();
+ });
+
+ test("keeps the title non-editable for a read-only block (no input on click)", () => {
+ act(() => {
+ useWorkflowPanelStore.getState().setSelectedBlockId("block-readonly");
+ });
+ render(
+ <MemoryRouter initialEntries={["/workflows/wpid_abc/edit"]}>
+ <BlockConfigSidebar />
+ </MemoryRouter>,
+ );
+
+ const title = screen.getByText("ReadOnly");
+ fireEvent.click(title);
+
+ expect(screen.queryByRole("textbox")).toBeNull();
+ expect(mockLabelChangeHandler).not.toHaveBeenCalled();
+ });
+});
diff --git a/skyvern-frontend/src/routes/workflows/editor/panels/BlockConfigSidebar.tsx b/skyvern-frontend/src/routes/workflows/editor/panels/BlockConfigSidebar.tsx
index 257644e76..870ac29b0 100644
--- a/skyvern-frontend/src/routes/workflows/editor/panels/BlockConfigSidebar.tsx
+++ b/skyvern-frontend/src/routes/workflows/editor/panels/BlockConfigSidebar.tsx
@@ -1,5 +1,5 @@
import { Cross2Icon, GearIcon, PlusIcon } from "@radix-ui/react-icons";
-import { useReactFlow } from "@xyflow/react";
+import { useNodesData, useReactFlow } from "@xyflow/react";
import { Resizable } from "re-resizable";
import { useEffect, useRef, useState } from "react";
@@ -13,8 +13,11 @@ import { useSidebarSaveStateStore } from "@/store/SidebarSaveStateStore";
import { useWorkflowPanelStore } from "@/store/WorkflowPanelStore";
import { cn } from "@/util/utils";
+import { useNodeLabelChangeHandler } from "@/routes/workflows/hooks/useLabelChangeHandler";
+
import { useWorkflowEditorMode } from "../hooks/useWorkflowEditorMode";
import { AppNode, isWorkflowBlockNode, WorkflowBlockNode } from "../nodes";
+import { EditableNodeTitle } from "../nodes/components/EditableNodeTitle";
import { isStartNode } from "../nodes/StartNode/types";
import { WorkflowBlockIcon } from "../nodes/WorkflowBlockIcon";
import { workflowBlockTitle } from "../nodes/types";
@@ -129,6 +132,47 @@ function SubLabel() {
);
}
+// Inline-editable block title, mirroring the canvas tile's NodeHeader. Reads
+// the live label/editable slice reactively so the heading reflects an edit
+// immediately, and routes commits through the same handler the canvas uses
+// (sanitize, dedupe, propagate the rename to parameter keys + collapse state).
+// Keyed on blockId by the caller so it re-initializes when the selection moves
+// to another block without remounting the surrounding sidebar shell. On
+// read-only (global) workflows it renders a plain heading: EditableNodeTitle
+// still enters its click-to-edit affordance when disabled, which would read
+// as misleadingly interactive.
+function EditableBlockTitle({
+ blockId,
+ fallbackLabel,
+}: Readonly<{ blockId: string; fallbackLabel: string }>) {
+ const data = useNodesData<WorkflowBlockNode>(blockId)?.data;
+ const label =
+ typeof data?.label === "string" && data.label.length > 0
+ ? data.label
+ : fallbackLabel;
+ const editable = Boolean(data?.editable);
+ const [, handleLabelChange] = useNodeLabelChangeHandler({
+ id: blockId,
+ initialValue: label,
+ });
+
+ if (!editable) {
+ return (
+ <h2 className="truncate text-sm font-medium text-slate-100">{label}</h2>
+ );
+ }
+
+ return (
+ <EditableNodeTitle
+ value={label}
+ editable
+ onChange={handleLabelChange}
+ titleClassName="text-sm font-medium text-slate-100"
+ inputClassName="text-sm font-medium text-slate-100"
+ />
+ );
+}
+
function BlockConfigSidebarBody({
selectedBlockId,
onClose,
@@ -163,9 +207,17 @@ function BlockConfigSidebarBody({
</div>
) : null}
<div className="min-w-0">
- <h2 className="truncate text-sm font-medium text-slate-100">
- {label}
- </h2>
+ {isStart ? (
+ <h2 className="truncate text-sm font-medium text-slate-100">
+ {label}
+ </h2>
+ ) : (
+ <EditableBlockTitle
+ key={selectedBlockId}
+ blockId={selectedBlockId}
+ fallbackLabel={label}
+ />
+ )}
<SubLabel />
</div>
</div>
diff --git a/skyvern/config.py b/skyvern/config.py
index d0275a3b3..80138041f 100644
--- a/skyvern/config.py
+++ b/skyvern/config.py
@@ -201,6 +201,15 @@ class Settings(BaseSettings):
AZURE_STORAGE_CONTAINER_BROWSER_SESSIONS: str = "skyvern-browser-sessions"
AZURE_STORAGE_CONTAINER_UPLOADS: str = "skyvern-uploads"
+ # Google Cloud Storage settings (bucket names are globally unique — override per deployment)
+ GCS_PROJECT_ID: str | None = None
+ GCS_BUCKET_ARTIFACTS: str = "skyvern-artifacts"
+ GCS_BUCKET_SCREENSHOTS: str = "skyvern-screenshots"
+ GCS_BUCKET_BROWSER_SESSIONS: str = "skyvern-browser-sessions"
+ GCS_BUCKET_UPLOADS: str = "skyvern-uploads"
+ # GSA email used to sign V4 URLs when running under Workload Identity (no local private key).
+ GCS_SIGNER_SA_EMAIL: str | None = None
+
SKYVERN_TELEMETRY: bool = True
ANALYTICS_ID: str = "anonymous"
ANALYTICS_TEST_ID: str | None = None
diff --git a/skyvern/forge/sdk/api/gcp.py b/skyvern/forge/sdk/api/gcp.py
new file mode 100644
index 000000000..d07c98f61
--- /dev/null
+++ b/skyvern/forge/sdk/api/gcp.py
@@ -0,0 +1,85 @@
+from typing import IO, Protocol
+from urllib.parse import urlparse
+
+
+class GcsUri:
+ """Parse gs://{bucket}/{object_path} URIs."""
+
+ def __init__(self, uri: str) -> None:
+ self._parsed = urlparse(uri, allow_fragments=False)
+
+ @property
+ def bucket(self) -> str:
+ return self._parsed.netloc
+
+ @property
+ def object_path(self) -> str:
+ if self._parsed.query:
+ return self._parsed.path.lstrip("/") + "?" + self._parsed.query
+ return self._parsed.path.lstrip("/")
+
+ @property
+ def uri(self) -> str:
+ return self._parsed.geturl()
+
+ def __str__(self) -> str:
+ return self.uri
+
+
+# GCS storage classes (the per-org tier lever, analogous to Azure StandardBlobTier).
+STORAGE_CLASS_STANDARD = "STANDARD"
+STORAGE_CLASS_NEARLINE = "NEARLINE"
+STORAGE_CLASS_COLDLINE = "COLDLINE"
+STORAGE_CLASS_ARCHIVE = "ARCHIVE"
+
+
+class AsyncGcsStorageClient(Protocol):
+ """Interface for GCS storage operations. Mirrors the method surface the
+ storage adapter relies on from the Azure client (upload/download/list/
+ signed-url), so ``GcsStorage`` can be a near-copy of ``AzureStorage``.
+ """
+
+ async def upload_file(
+ self,
+ uri: str,
+ data: bytes,
+ storage_class: str = STORAGE_CLASS_STANDARD,
+ tags: dict[str, str] | None = None,
+ metadata: dict[str, str] | None = None,
+ ) -> None: ...
+
+ async def upload_file_from_path(
+ self,
+ uri: str,
+ file_path: str,
+ storage_class: str = STORAGE_CLASS_STANDARD,
+ tags: dict[str, str] | None = None,
+ metadata: dict[str, str] | None = None,
+ ) -> None: ...
+
+ async def upload_file_stream(
+ self,
+ uri: str,
+ file_obj: IO[bytes],
+ storage_class: str = STORAGE_CLASS_STANDARD,
+ tags: dict[str, str] | None = None,
+ metadata: dict[str, str] | None = None,
+ ) -> str: ...
+
+ async def download_file(self, uri: str, log_exception: bool = True) -> bytes | None: ...
+
+ async def delete_file(self, uri: str) -> None: ...
+
+ async def list_files(self, uri: str) -> list[str]: ...
+
+ async def get_object_info(self, uri: str) -> dict | None: ...
+
+ async def create_signed_urls(self, uris: list[str], expiry_hours: int = 24) -> list[str] | None: ...
+
+ async def close(self) -> None: ...
+
+
+class GcpClientFactory(Protocol):
+ """Interface for creating GCS storage clients."""
+
+ def create_storage_client(self, project_id: str | None = None) -> "AsyncGcsStorageClient": ...
diff --git a/skyvern/forge/sdk/api/real_gcp.py b/skyvern/forge/sdk/api/real_gcp.py
new file mode 100644
index 000000000..5df0d988a
--- /dev/null
+++ b/skyvern/forge/sdk/api/real_gcp.py
@@ -0,0 +1,232 @@
+"""Real implementation of the GCS storage client and its factory.
+
+``google-cloud-storage`` is synchronous, so every blocking call is wrapped in
+``asyncio.to_thread`` to satisfy the async ``AsyncGcsStorageClient`` interface.
+"""
+
+import asyncio
+from datetime import timedelta
+from mimetypes import add_type, guess_type
+from typing import IO
+
+import structlog
+from google.api_core.exceptions import NotFound
+from google.auth import default as google_auth_default
+from google.auth.credentials import Credentials
+from google.auth.transport.requests import Request as GoogleAuthRequest
+from google.cloud import storage
+
+from skyvern.config import settings
+from skyvern.forge.sdk.api.gcp import (
+ STORAGE_CLASS_STANDARD,
+ AsyncGcsStorageClient,
+ GcpClientFactory,
+ GcsUri,
+)
+
+# Match the custom mime types registered for the Azure client.
+add_type("application/json", ".har")
+add_type("text/plain", ".log")
+add_type("application/zstd", ".zst")
+
+_SIGNING_SCOPES = ["https://www.googleapis.com/auth/cloud-platform"]
+
+LOG = structlog.get_logger()
+
+
+class RealAsyncGcsStorageClient(AsyncGcsStorageClient):
+ """Async wrapper over the synchronous ``google.cloud.storage`` client."""
+
+ def __init__(
+ self,
+ project_id: str | None = None,
+ credentials: Credentials | None = None,
+ ) -> None:
+ self.project_id = project_id or settings.GCS_PROJECT_ID
+ self._credentials = credentials
+ self._client: storage.Client | None = None
+
+ def _get_client(self) -> storage.Client:
+ if self._client is None:
+ # When credentials are omitted the client resolves Application
+ # Default Credentials (GOOGLE_APPLICATION_CREDENTIALS / Workload
+ # Identity). STORAGE_EMULATOR_HOST is honored automatically.
+ self._client = storage.Client(project=self.project_id, credentials=self._credentials)
+ return self._client
+
+ def _get_blob(self, uri: str) -> storage.Blob:
+ parsed = GcsUri(uri)
+ bucket = self._get_client().bucket(parsed.bucket)
+ return bucket.blob(parsed.object_path)
+
+ async def upload_file(
+ self,
+ uri: str,
+ data: bytes,
+ storage_class: str = STORAGE_CLASS_STANDARD,
+ tags: dict[str, str] | None = None,
+ metadata: dict[str, str] | None = None,
+ ) -> None:
+ def _do() -> None:
+ blob = self._get_blob(uri)
+ blob.storage_class = storage_class
+ if metadata:
+ blob.metadata = metadata
+ content_type, _ = guess_type(GcsUri(uri).object_path)
+ blob.upload_from_string(data, content_type=content_type)
+
+ await asyncio.to_thread(_do)
+
+ async def upload_file_from_path(
+ self,
+ uri: str,
+ file_path: str,
+ storage_class: str = STORAGE_CLASS_STANDARD,
+ tags: dict[str, str] | None = None,
+ metadata: dict[str, str] | None = None,
+ ) -> None:
+ def _do() -> None:
+ blob = self._get_blob(uri)
+ blob.storage_class = storage_class
+ if metadata:
+ blob.metadata = metadata
+ content_type, _ = guess_type(file_path)
+ blob.upload_from_filename(file_path, content_type=content_type)
+
+ await asyncio.to_thread(_do)
+
+ async def upload_file_stream(
+ self,
+ uri: str,
+ file_obj: IO[bytes],
+ storage_class: str = STORAGE_CLASS_STANDARD,
+ tags: dict[str, str] | None = None,
+ metadata: dict[str, str] | None = None,
+ ) -> str:
+ def _do() -> None:
+ blob = self._get_blob(uri)
+ blob.storage_class = storage_class
+ if metadata:
+ blob.metadata = metadata
+ content_type, _ = guess_type(GcsUri(uri).object_path)
+ blob.upload_from_file(file_obj, content_type=content_type)
+
+ await asyncio.to_thread(_do)
+ return uri
+
+ async def download_file(self, uri: str, log_exception: bool = True) -> bytes | None:
+ def _do() -> bytes | None:
+ try:
+ return self._get_blob(uri).download_as_bytes()
+ except NotFound:
+ if log_exception:
+ LOG.warning("GCS object not found", uri=uri)
+ return None
+ except Exception:
+ if log_exception:
+ LOG.exception("Failed to download from GCS", uri=uri)
+ return None
+
+ return await asyncio.to_thread(_do)
+
+ async def delete_file(self, uri: str) -> None:
+ def _do() -> None:
+ try:
+ self._get_blob(uri).delete()
+ except NotFound:
+ LOG.debug("GCS object not found for deletion", uri=uri)
+ except Exception:
+ LOG.exception("Failed to delete GCS object", uri=uri)
+ raise
+
+ await asyncio.to_thread(_do)
+
+ async def list_files(self, uri: str) -> list[str]:
+ def _do() -> list[str]:
+ parsed = GcsUri(uri)
+ try:
+ blobs = self._get_client().list_blobs(parsed.bucket, prefix=parsed.object_path)
+ return [blob.name for blob in blobs]
+ except NotFound:
+ return []
+ except Exception:
+ LOG.exception("Failed to list GCS objects", bucket=parsed.bucket, prefix=parsed.object_path)
+ return []
+
+ return await asyncio.to_thread(_do)
+
+ async def get_object_info(self, uri: str) -> dict | None:
+ def _do() -> dict | None:
+ parsed = GcsUri(uri)
+ bucket = self._get_client().bucket(parsed.bucket)
+ blob = bucket.get_blob(parsed.object_path)
+ if blob is None:
+ return None
+ return {
+ "Metadata": blob.metadata or {},
+ "LastModified": blob.updated,
+ "ContentLength": blob.size,
+ }
+
+ return await asyncio.to_thread(_do)
+
+ def _signing_kwargs(self) -> dict:
+ """Extra kwargs for ``generate_signed_url``.
+
+ With a local private key (SA JSON key) signing happens locally and no
+ extra kwargs are needed. Under Workload Identity there is no private
+ key, so we route to the IAM ``signBlob`` API by passing the signer's
+ email + a fresh access token — requires ``GCS_SIGNER_SA_EMAIL`` set and
+ ``roles/iam.serviceAccountTokenCreator`` on that SA.
+ """
+ if not settings.GCS_SIGNER_SA_EMAIL:
+ return {}
+ creds, _ = google_auth_default(scopes=_SIGNING_SCOPES)
+ creds.refresh(GoogleAuthRequest())
+ return {"service_account_email": settings.GCS_SIGNER_SA_EMAIL, "access_token": creds.token}
+
+ def _create_signed_url(self, uri: str, expiry_hours: int = 24, signing_kwargs: dict | None = None) -> str | None:
+ # Private + synchronous: does blocking signing I/O (and, under Workload
+ # Identity, a token refresh). Call only from create_signed_urls, which
+ # runs it inside asyncio.to_thread so the event loop isn't blocked.
+ # signing_kwargs holds the freshly-minted IAM token; the batch caller
+ # passes it in once rather than refreshing per URL.
+ if signing_kwargs is None:
+ signing_kwargs = self._signing_kwargs()
+ try:
+ blob = self._get_blob(uri)
+ return blob.generate_signed_url(
+ version="v4",
+ expiration=timedelta(hours=expiry_hours),
+ method="GET",
+ **signing_kwargs,
+ )
+ except Exception:
+ LOG.exception("Failed to create signed URL", uri=uri)
+ return None
+
+ async def create_signed_urls(self, uris: list[str], expiry_hours: int = 24) -> list[str] | None:
+ def _do() -> list[str] | None:
+ signing_kwargs = self._signing_kwargs()
+ signed_urls: list[str] = []
+ for uri in uris:
+ url = self._create_signed_url(uri, expiry_hours, signing_kwargs=signing_kwargs)
+ if url is None:
+ LOG.warning("Signed URL generation failed, aborting batch", failed_uri=uri, uris=uris)
+ return None
+ signed_urls.append(url)
+ return signed_urls
+
+ return await asyncio.to_thread(_do)
+
+ async def close(self) -> None:
+ if self._client is not None:
+ self._client.close()
+ self._client = None
+
+
+class RealGcpClientFactory(GcpClientFactory):
+ """Factory for creating real GCS storage clients."""
+
+ def create_storage_client(self, project_id: str | None = None) -> AsyncGcsStorageClient:
+ return RealAsyncGcsStorageClient(project_id=project_id)
diff --git a/skyvern/forge/sdk/artifact/storage/gcs.py b/skyvern/forge/sdk/artifact/storage/gcs.py
new file mode 100644
index 000000000..288d1dc05
--- /dev/null
+++ b/skyvern/forge/sdk/artifact/storage/gcs.py
@@ -0,0 +1,861 @@
+import os
+import shutil
+import uuid
+from datetime import datetime, timezone
+from typing import BinaryIO
+
+import structlog
+
+from skyvern.config import settings
+from skyvern.constants import BROWSER_DOWNLOADING_SUFFIX, DOWNLOAD_FILE_PREFIX
+from skyvern.forge import app
+from skyvern.forge.sdk.api.files import (
+ calculate_sha256_for_file,
+ create_named_temporary_file,
+ get_download_dir,
+ get_skyvern_temp_dir,
+ make_temp_directory,
+ unzip_files,
+)
+from skyvern.forge.sdk.api.gcp import STORAGE_CLASS_STANDARD, GcsUri
+from skyvern.forge.sdk.api.real_gcp import RealAsyncGcsStorageClient
+from skyvern.forge.sdk.artifact.models import Artifact, ArtifactType, LogEntityType
+from skyvern.forge.sdk.artifact.storage.base import (
+ FILE_EXTENTSION_MAP,
+ BaseStorage,
+ _file_infos_from_artifacts,
+ _file_infos_from_download_artifacts,
+)
+from skyvern.forge.sdk.models import Step
+from skyvern.forge.sdk.schemas.ai_suggestions import AISuggestion
+from skyvern.forge.sdk.schemas.files import FileInfo
+from skyvern.forge.sdk.schemas.task_v2 import TaskV2, Thought
+from skyvern.forge.sdk.schemas.workflow_runs import WorkflowRunBlock
+
+LOG = structlog.get_logger()
+
+
+def _safe_get_file_size(path: str) -> int | None:
+ try:
+ return os.path.getsize(path)
+ except OSError:
+ LOG.warning("Failed to get file size", path=path, exc_info=True)
+ return None
+
+
+async def _get_object_info_safe(storage: "GcsStorage", uri: str) -> dict | None:
+ try:
+ return await storage.async_client.get_object_info(uri)
+ except Exception:
+ LOG.warning("Object info retrieval failed", uri=uri, exc_info=True)
+ return None
+
+
+class GcsStorage(BaseStorage):
+ _PATH_VERSION = "v1"
+
+ def __init__(
+ self,
+ bucket: str | None = None,
+ project_id: str | None = None,
+ ) -> None:
+ self.async_client = RealAsyncGcsStorageClient(project_id=project_id)
+ self.bucket = bucket or settings.GCS_BUCKET_ARTIFACTS
+
+ def build_uri(self, *, organization_id: str, artifact_id: str, step: Step, artifact_type: ArtifactType) -> str:
+ file_ext = FILE_EXTENTSION_MAP[artifact_type]
+ return f"{self._build_base_uri(organization_id)}/{step.task_id}/{step.order:02d}_{step.retry_index}_{step.step_id}/{datetime.utcnow().isoformat()}_{artifact_id}_{artifact_type}.{file_ext}"
+
+ async def retrieve_global_workflows(self) -> list[str]:
+ uri = f"gs://{self.bucket}/{settings.ENV}/global_workflows.txt"
+ data = await self.async_client.download_file(uri, log_exception=False)
+ if not data:
+ return []
+ return [line.strip() for line in data.decode("utf-8").split("\n") if line.strip()]
+
+ def _build_base_uri(self, organization_id: str) -> str:
+ return f"gs://{self.bucket}/{self._PATH_VERSION}/{settings.ENV}/{organization_id}"
+
+ def build_log_uri(
+ self, *, organization_id: str, log_entity_type: LogEntityType, log_entity_id: str, artifact_type: ArtifactType
+ ) -> str:
+ file_ext = FILE_EXTENTSION_MAP[artifact_type]
+ return f"{self._build_base_uri(organization_id)}/logs/{log_entity_type}/{log_entity_id}/{datetime.utcnow().isoformat()}_{artifact_type}.{file_ext}"
+
+ def build_thought_uri(
+ self, *, organization_id: str, artifact_id: str, thought: Thought, artifact_type: ArtifactType
+ ) -> str:
+ file_ext = FILE_EXTENTSION_MAP[artifact_type]
+ return f"{self._build_base_uri(organization_id)}/observers/{thought.observer_cruise_id}/{thought.observer_thought_id}/{datetime.utcnow().isoformat()}_{artifact_id}_{artifact_type}.{file_ext}"
+
+ def build_task_v2_uri(
+ self, *, organization_id: str, artifact_id: str, task_v2: TaskV2, artifact_type: ArtifactType
+ ) -> str:
+ file_ext = FILE_EXTENTSION_MAP[artifact_type]
+ return f"{self._build_base_uri(organization_id)}/observers/{task_v2.observer_cruise_id}/{datetime.utcnow().isoformat()}_{artifact_id}_{artifact_type}.{file_ext}"
+
+ def build_workflow_run_block_uri(
+ self,
+ *,
+ organization_id: str,
+ artifact_id: str,
+ workflow_run_block: WorkflowRunBlock,
+ artifact_type: ArtifactType,
+ ) -> str:
+ file_ext = FILE_EXTENTSION_MAP[artifact_type]
+ return f"{self._build_base_uri(organization_id)}/workflow_runs/{workflow_run_block.workflow_run_id}/{workflow_run_block.workflow_run_block_id}/{datetime.utcnow().isoformat()}_{artifact_id}_{artifact_type}.{file_ext}"
+
+ def build_ai_suggestion_uri(
+ self, *, organization_id: str, artifact_id: str, ai_suggestion: AISuggestion, artifact_type: ArtifactType
+ ) -> str:
+ file_ext = FILE_EXTENTSION_MAP[artifact_type]
+ return f"{self._build_base_uri(organization_id)}/ai_suggestions/{ai_suggestion.ai_suggestion_id}/{datetime.utcnow().isoformat()}_{artifact_id}_{artifact_type}.{file_ext}"
+
+ def build_script_file_uri(
+ self, *, organization_id: str, script_id: str, script_version: int, file_path: str
+ ) -> str:
+ """Build the GCS URI for a script file."""
+ return f"{self._build_base_uri(organization_id)}/scripts/{script_id}/{script_version}/{file_path}"
+
+ async def store_artifact(self, artifact: Artifact, data: bytes) -> None:
+ storage_class = await self._get_storage_class_for_org(artifact.organization_id)
+ tags = await self._get_tags_for_org(artifact.organization_id)
+ LOG.debug(
+ "Storing artifact",
+ artifact_id=artifact.artifact_id,
+ organization_id=artifact.organization_id,
+ uri=artifact.uri,
+ storage_class=storage_class,
+ tags=tags,
+ )
+ await self.async_client.upload_file(artifact.uri, data, storage_class=storage_class, tags=tags)
+
+ async def _get_storage_class_for_org(self, organization_id: str | None) -> str:
+ return STORAGE_CLASS_STANDARD
+
+ async def _get_tags_for_org(self, organization_id: str) -> dict[str, str]:
+ return {}
+
+ async def retrieve_artifact(self, artifact: Artifact) -> bytes | None:
+ return await self.async_client.download_file(artifact.uri)
+
+ async def get_share_link(self, artifact: Artifact) -> str | None:
+ share_urls = await self.async_client.create_signed_urls([artifact.uri])
+ return share_urls[0] if share_urls else None
+
+ async def get_share_links(self, artifacts: list[Artifact]) -> list[str] | None:
+ return await self.async_client.create_signed_urls([artifact.uri for artifact in artifacts])
+
+ async def store_artifact_from_path(self, artifact: Artifact, path: str) -> None:
+ storage_class = await self._get_storage_class_for_org(artifact.organization_id)
+ tags = await self._get_tags_for_org(artifact.organization_id)
+ LOG.debug(
+ "Storing artifact from path",
+ artifact_id=artifact.artifact_id,
+ organization_id=artifact.organization_id,
+ uri=artifact.uri,
+ storage_class=storage_class,
+ path=path,
+ tags=tags,
+ )
+ await self.async_client.upload_file_from_path(artifact.uri, path, storage_class=storage_class, tags=tags)
+
+ async def save_streaming_file(self, organization_id: str, file_name: str) -> None:
+ from_path = f"{get_skyvern_temp_dir()}/{organization_id}/{file_name}"
+ to_path = f"gs://{settings.GCS_BUCKET_SCREENSHOTS}/{settings.ENV}/{organization_id}/{file_name}"
+ storage_class = await self._get_storage_class_for_org(organization_id)
+ tags = await self._get_tags_for_org(organization_id)
+ LOG.debug(
+ "Saving streaming file",
+ organization_id=organization_id,
+ file_name=file_name,
+ from_path=from_path,
+ to_path=to_path,
+ storage_class=storage_class,
+ tags=tags,
+ )
+ await self.async_client.upload_file_from_path(to_path, from_path, storage_class=storage_class, tags=tags)
+
+ async def get_streaming_file(self, organization_id: str, file_name: str, use_default: bool = True) -> bytes | None:
+ path = f"gs://{settings.GCS_BUCKET_SCREENSHOTS}/{settings.ENV}/{organization_id}/{file_name}"
+ return await self.async_client.download_file(path, log_exception=False)
+
+ async def store_browser_session(self, organization_id: str, workflow_permanent_id: str, directory: str) -> None:
+ # Zip the directory to a temp file
+ temp_zip_file = create_named_temporary_file()
+ zip_file_path = shutil.make_archive(temp_zip_file.name, "zip", directory)
+ browser_session_uri = (
+ f"gs://{settings.GCS_BUCKET_BROWSER_SESSIONS}/{settings.ENV}/{organization_id}/{workflow_permanent_id}.zip"
+ )
+ storage_class = await self._get_storage_class_for_org(organization_id)
+ tags = await self._get_tags_for_org(organization_id)
+ LOG.debug(
+ "Storing browser session",
+ organization_id=organization_id,
+ workflow_permanent_id=workflow_permanent_id,
+ zip_file_path=zip_file_path,
+ browser_session_uri=browser_session_uri,
+ storage_class=storage_class,
+ tags=tags,
+ )
+ await self.async_client.upload_file_from_path(
+ browser_session_uri, zip_file_path, storage_class=storage_class, tags=tags
+ )
+
+ async def retrieve_browser_session(self, organization_id: str, workflow_permanent_id: str) -> str | None:
+ browser_session_uri = (
+ f"gs://{settings.GCS_BUCKET_BROWSER_SESSIONS}/{settings.ENV}/{organization_id}/{workflow_permanent_id}.zip"
+ )
+ downloaded_zip_bytes = await self.async_client.download_file(browser_session_uri, log_exception=True)
+ if not downloaded_zip_bytes:
+ return None
+ temp_zip_file = create_named_temporary_file(delete=False)
+ temp_zip_file.write(downloaded_zip_bytes)
+ temp_zip_file_path = temp_zip_file.name
+
+ temp_dir = make_temp_directory(prefix="skyvern_browser_session_")
+ unzip_files(temp_zip_file_path, temp_dir)
+ temp_zip_file.close()
+ return temp_dir
+
+ async def delete_browser_session(self, organization_id: str, workflow_permanent_id: str) -> None:
+ browser_session_uri = (
+ f"gs://{settings.GCS_BUCKET_BROWSER_SESSIONS}/{settings.ENV}/{organization_id}/{workflow_permanent_id}.zip"
+ )
+ LOG.info(
+ "Deleting persisted browser session",
+ organization_id=organization_id,
+ workflow_permanent_id=workflow_permanent_id,
+ browser_session_uri=browser_session_uri,
+ )
+ await self.async_client.delete_file(browser_session_uri)
+
+ async def store_browser_profile(self, organization_id: str, profile_id: str, directory: str) -> None:
+ """Store browser profile to GCS."""
+ temp_zip_file = create_named_temporary_file()
+ zip_file_path = shutil.make_archive(temp_zip_file.name, "zip", directory)
+ profile_uri = (
+ f"gs://{settings.GCS_BUCKET_BROWSER_SESSIONS}/{settings.ENV}/{organization_id}/profiles/{profile_id}.zip"
+ )
+ storage_class = await self._get_storage_class_for_org(organization_id)
+ tags = await self._get_tags_for_org(organization_id)
+ LOG.debug(
+ "Storing browser profile",
+ organization_id=organization_id,
+ profile_id=profile_id,
+ zip_file_path=zip_file_path,
+ profile_uri=profile_uri,
+ storage_class=storage_class,
+ tags=tags,
+ )
+ await self.async_client.upload_file_from_path(
+ profile_uri, zip_file_path, storage_class=storage_class, tags=tags
+ )
+
+ async def retrieve_browser_profile(self, organization_id: str, profile_id: str) -> str | None:
+ """Retrieve browser profile from GCS."""
+ profile_uri = (
+ f"gs://{settings.GCS_BUCKET_BROWSER_SESSIONS}/{settings.ENV}/{organization_id}/profiles/{profile_id}.zip"
+ )
+ downloaded_zip_bytes = await self.async_client.download_file(profile_uri, log_exception=True)
+ if not downloaded_zip_bytes:
+ return None
+ temp_zip_file = create_named_temporary_file(delete=False)
+ temp_zip_file.write(downloaded_zip_bytes)
+ temp_zip_file_path = temp_zip_file.name
+
+ temp_dir = make_temp_directory(prefix="skyvern_browser_profile_")
+ unzip_files(temp_zip_file_path, temp_dir)
+ temp_zip_file.close()
+ return temp_dir
+
+ async def list_downloaded_files_in_browser_session(
+ self, organization_id: str, browser_session_id: str
+ ) -> list[str]:
+ """Return GCS URIs of completed downloads. DB-backed; mirrors s3.py."""
+ return await self._list_downloads_for_session(
+ organization_id=organization_id,
+ browser_session_id=browser_session_id,
+ in_progress=False,
+ )
+
+ async def _list_downloads_for_session(
+ self,
+ *,
+ organization_id: str,
+ browser_session_id: str,
+ in_progress: bool,
+ ) -> list[str]:
+ """Shared DB-backed lister with a partial-vs-final discriminator."""
+ if settings.ARTIFACT_CONTENT_HMAC_KEYRING:
+ try:
+ artifacts = await app.DATABASE.artifacts.list_artifacts_for_browser_session_by_type(
+ browser_session_id=browser_session_id,
+ organization_id=organization_id,
+ artifact_type=ArtifactType.DOWNLOAD,
+ )
+ except Exception:
+ LOG.warning(
+ "Failed to list browser-session download artifacts; falling back to GCS LIST",
+ organization_id=organization_id,
+ browser_session_id=browser_session_id,
+ in_progress=in_progress,
+ exc_info=True,
+ )
+ artifacts = None
+ if artifacts is not None:
+ return [a.uri for a in artifacts if a.uri and a.uri.endswith(BROWSER_DOWNLOADING_SUFFIX) == in_progress]
+
+ uri = f"gs://{settings.GCS_BUCKET_ARTIFACTS}/v1/{settings.ENV}/{organization_id}/browser_sessions/{browser_session_id}/downloads"
+ files = [f"gs://{settings.GCS_BUCKET_ARTIFACTS}/{file}" for file in await self.async_client.list_files(uri=uri)]
+ return [f for f in files if f.endswith(BROWSER_DOWNLOADING_SUFFIX) == in_progress]
+
+ async def get_shared_downloaded_files_in_browser_session(
+ self, organization_id: str, browser_session_id: str
+ ) -> list[FileInfo]:
+ # Artifact-first when keyring is configured — see s3.py for rationale.
+ if settings.ARTIFACT_CONTENT_HMAC_KEYRING:
+ try:
+ artifacts = await app.DATABASE.artifacts.list_artifacts_for_browser_session_by_type(
+ browser_session_id=browser_session_id,
+ organization_id=organization_id,
+ artifact_type=ArtifactType.DOWNLOAD,
+ )
+ except Exception:
+ LOG.warning(
+ "Failed to look up browser-session download artifacts; falling back to signed URLs",
+ organization_id=organization_id,
+ browser_session_id=browser_session_id,
+ exc_info=True,
+ )
+ artifacts = []
+ # Filter out in-progress partials — user-facing listing must only
+ # show completed downloads. Mirrors s3.py.
+ artifacts = [a for a in artifacts if a.uri and not a.uri.endswith(BROWSER_DOWNLOADING_SUFFIX)]
+ if artifacts:
+ return await _file_infos_from_download_artifacts(artifacts)
+
+ return await self._get_shared_downloaded_files_in_browser_session_via_listing(
+ organization_id=organization_id, browser_session_id=browser_session_id
+ )
+
+ async def _get_shared_downloaded_files_in_browser_session_via_listing(
+ self, *, organization_id: str, browser_session_id: str
+ ) -> list[FileInfo]:
+ # Direct GCS LIST: legacy fallback for sessions pre-cutover.
+ # ``list_downloaded_files_in_browser_session`` is now DB-backed, so
+ # we can't reuse it here.
+ listing_uri = f"gs://{settings.GCS_BUCKET_ARTIFACTS}/v1/{settings.ENV}/{organization_id}/browser_sessions/{browser_session_id}/downloads"
+ object_keys = [
+ f"gs://{settings.GCS_BUCKET_ARTIFACTS}/{file}"
+ for file in await self.async_client.list_files(uri=listing_uri)
+ if not file.endswith(BROWSER_DOWNLOADING_SUFFIX)
+ ]
+ if len(object_keys) == 0:
+ return []
+
+ file_infos: list[FileInfo] = []
+ for key in object_keys:
+ metadata = {}
+ modified_at: datetime | None = None
+ content_length: int | None = None
+ # Get metadata (including checksum)
+ object_info = await _get_object_info_safe(self, key)
+ if object_info:
+ metadata = object_info.get("Metadata", {})
+ modified_at = object_info.get("LastModified")
+ content_length = object_info.get("ContentLength")
+
+ # Create FileInfo object
+ filename = os.path.basename(key)
+ checksum = metadata.get("sha256_checksum") if metadata else None
+
+ # Get signed URL
+ signed_urls = await self.async_client.create_signed_urls([key])
+ if not signed_urls:
+ continue
+
+ file_info = FileInfo(
+ url=signed_urls[0],
+ checksum=checksum,
+ filename=metadata.get("original_filename", filename) if metadata else filename,
+ file_size=content_length,
+ modified_at=modified_at,
+ )
+ file_infos.append(file_info)
+
+ return file_infos
+
+ async def list_downloading_files_in_browser_session(
+ self, organization_id: str, browser_session_id: str
+ ) -> list[str]:
+ """Return GCS URIs of in-progress (``*.crdownload``) downloads. DB-backed."""
+ return await self._list_downloads_for_session(
+ organization_id=organization_id,
+ browser_session_id=browser_session_id,
+ in_progress=True,
+ )
+
+ async def get_shared_recordings_in_browser_session(
+ self, organization_id: str, browser_session_id: str
+ ) -> list[FileInfo]:
+ """Get recording files for a browser session.
+
+ Artifact-first when the keyring is configured — see s3.py for the
+ rationale. Falls back to direct GCS LIST + signed URLs for legacy
+ sessions and OSS-default deployments.
+ """
+ if settings.ARTIFACT_CONTENT_HMAC_KEYRING:
+ try:
+ artifacts = await app.DATABASE.artifacts.list_artifacts_for_browser_session_by_type(
+ browser_session_id=browser_session_id,
+ organization_id=organization_id,
+ artifact_type=ArtifactType.RECORDING,
+ )
+ except Exception:
+ LOG.warning(
+ "Failed to look up browser-session recording artifacts; falling back to signed URLs",
+ organization_id=organization_id,
+ browser_session_id=browser_session_id,
+ exc_info=True,
+ )
+ artifacts = []
+ artifacts = [
+ a for a in artifacts if a.uri and (a.uri.lower().endswith(".webm") or a.uri.lower().endswith(".mp4"))
+ ]
+ if artifacts:
+ file_infos = await _file_infos_from_artifacts(artifacts, artifact_type=ArtifactType.RECORDING)
+ file_infos.sort(key=lambda f: (f.modified_at is not None, f.modified_at), reverse=True)
+ return file_infos
+
+ return await self._get_shared_recordings_in_browser_session_via_listing(
+ organization_id=organization_id, browser_session_id=browser_session_id
+ )
+
+ async def _get_shared_recordings_in_browser_session_via_listing(
+ self, *, organization_id: str, browser_session_id: str
+ ) -> list[FileInfo]:
+ # Direct GCS LIST: legacy fallback for pre-cutover sessions and
+ # OSS deployments without a keyring.
+ listing_uri = f"gs://{settings.GCS_BUCKET_ARTIFACTS}/v1/{settings.ENV}/{organization_id}/browser_sessions/{browser_session_id}/videos"
+ object_keys = [
+ f"gs://{settings.GCS_BUCKET_ARTIFACTS}/{file}"
+ for file in await self.async_client.list_files(uri=listing_uri)
+ ]
+ if len(object_keys) == 0:
+ return []
+
+ file_infos: list[FileInfo] = []
+ for key in object_keys:
+ # Playwright's record_video_dir should only contain .webm files.
+ # Filter defensively in case of unexpected files.
+ key_lower = key.lower()
+ if not (key_lower.endswith(".webm") or key_lower.endswith(".mp4")):
+ LOG.warning(
+ "Skipping recording file with unsupported extension",
+ uri=key,
+ organization_id=organization_id,
+ browser_session_id=browser_session_id,
+ )
+ continue
+
+ metadata = {}
+ modified_at: datetime | None = None
+ content_length: int | None = None
+ # Get metadata (including checksum)
+ object_info = await _get_object_info_safe(self, key)
+ if object_info:
+ metadata = object_info.get("Metadata", {})
+ modified_at = object_info.get("LastModified")
+ content_length = object_info.get("ContentLength")
+
+ # Skip zero-byte objects (if any incomplete uploads)
+ if content_length == 0:
+ continue
+
+ # Create FileInfo object
+ filename = os.path.basename(key)
+ checksum = metadata.get("sha256_checksum") if metadata else None
+
+ # Get signed URL
+ signed_urls = await self.async_client.create_signed_urls([key])
+ if not signed_urls:
+ continue
+
+ file_info = FileInfo(
+ url=signed_urls[0],
+ checksum=checksum,
+ filename=metadata.get("original_filename", filename) if metadata else filename,
+ file_size=content_length,
+ modified_at=modified_at,
+ )
+ file_infos.append(file_info)
+
+ # Prefer the newest recording first (GCS list order is not guaranteed).
+ # Treat None as "oldest".
+ file_infos.sort(key=lambda f: (f.modified_at is not None, f.modified_at), reverse=True)
+ return file_infos
+
+ async def save_downloaded_files(
+ self,
+ organization_id: str,
+ run_id: str | None,
+ ) -> None:
+ storage_class = await self._get_storage_class_for_org(organization_id)
+ tags = await self._get_tags_for_org(organization_id)
+ base_uri = (
+ f"gs://{settings.GCS_BUCKET_UPLOADS}/{DOWNLOAD_FILE_PREFIX}/{settings.ENV}/{organization_id}/{run_id}"
+ )
+
+ await self._save_downloaded_files_from_local(
+ organization_id=organization_id,
+ base_uri=base_uri,
+ run_id=run_id,
+ storage_class=storage_class,
+ tags=tags,
+ )
+
+ async def _save_downloaded_files_from_local(
+ self,
+ organization_id: str,
+ base_uri: str,
+ run_id: str | None,
+ storage_class: str,
+ tags: dict[str, str] | None,
+ ) -> None:
+ """Save files from local download directory to GCS."""
+ download_dir = get_download_dir(run_id=run_id)
+ files = os.listdir(download_dir)
+ for file in files:
+ fpath = os.path.join(download_dir, file)
+ if not os.path.isfile(fpath):
+ continue
+ uri = f"{base_uri}/{file}"
+ checksum = calculate_sha256_for_file(fpath)
+ file_size = _safe_get_file_size(fpath)
+ # GCS custom metadata values must be ASCII (sent as HTTP headers);
+ # preserve the full filename via the object path / Artifact URI instead.
+ metadata: dict[str, str] = {"sha256_checksum": checksum}
+ if file.isascii():
+ metadata["original_filename"] = file
+ # Catch upload failures so we never create an Artifact row for
+ # bytes that didn't actually land in storage.
+ try:
+ await self.async_client.upload_file_from_path(
+ uri=uri,
+ file_path=fpath,
+ metadata=metadata,
+ storage_class=storage_class,
+ tags=tags,
+ )
+ except Exception:
+ LOG.warning(
+ "Skipping downloaded file — GCS upload failed",
+ file=file,
+ organization_id=organization_id,
+ run_id=run_id,
+ exc_info=True,
+ )
+ continue
+
+ # Register the file as an Artifact so GET run output can serve it via
+ # the signed /v1/artifacts/{id}/content endpoint. Persist the SHA-256 we already
+ # computed so retrieval doesn't need an extra object HEAD per file.
+ if run_id is not None:
+ try:
+ await app.ARTIFACT_MANAGER.create_download_artifact(
+ organization_id=organization_id,
+ run_id=run_id,
+ uri=uri,
+ filename=file,
+ checksum=checksum,
+ file_size=file_size,
+ )
+ except Exception:
+ LOG.warning(
+ "Failed to register downloaded file as artifact; falling back to signed URLs for retrieval",
+ file=file,
+ organization_id=organization_id,
+ run_id=run_id,
+ exc_info=True,
+ )
+
+ async def get_downloaded_files(self, organization_id: str, run_id: str | None) -> list[FileInfo]:
+ # Artifact-first — see s3.py::get_downloaded_files for rationale. When
+ # the keyring isn't configured (OSS default) or no artifact rows exist
+ # (legacy run) we fall back to the legacy listing path so
+ # downloaded files remain reachable.
+ if run_id is not None and settings.ARTIFACT_CONTENT_HMAC_KEYRING:
+ artifacts = await self._list_download_artifacts_safe(organization_id=organization_id, run_id=run_id)
+ if artifacts:
+ return await _file_infos_from_download_artifacts(artifacts)
+
+ return await self._get_downloaded_files_via_blob_listing(organization_id=organization_id, run_id=run_id)
+
+ async def _list_download_artifacts_safe(self, *, organization_id: str, run_id: str) -> list[Artifact]:
+ try:
+ return await app.DATABASE.artifacts.list_artifacts_for_run_by_type(
+ run_id=run_id,
+ organization_id=organization_id,
+ artifact_type=ArtifactType.DOWNLOAD,
+ )
+ except Exception:
+ LOG.warning(
+ "Failed to look up download artifacts; falling back to signed URLs",
+ organization_id=organization_id,
+ run_id=run_id,
+ exc_info=True,
+ )
+ return []
+
+ async def _get_downloaded_files_via_blob_listing(
+ self, *, organization_id: str, run_id: str | None
+ ) -> list[FileInfo]:
+ uri = f"gs://{settings.GCS_BUCKET_UPLOADS}/{DOWNLOAD_FILE_PREFIX}/{settings.ENV}/{organization_id}/{run_id}"
+ object_keys = await self.async_client.list_files(uri=uri)
+ if len(object_keys) == 0:
+ return []
+
+ file_infos: list[FileInfo] = []
+ for key in object_keys:
+ object_uri = f"gs://{settings.GCS_BUCKET_UPLOADS}/{key}"
+
+ metadata = {}
+ content_length: int | None = None
+ object_info = await _get_object_info_safe(self, object_uri)
+ if object_info:
+ metadata = object_info.get("Metadata", {})
+ content_length = object_info.get("ContentLength")
+ filename = os.path.basename(key)
+ checksum = metadata.get("sha256_checksum") if metadata else None
+ display_name = metadata.get("original_filename", filename) if metadata else filename
+
+ signed_urls = await self.async_client.create_signed_urls([object_uri])
+ if not signed_urls:
+ continue
+
+ file_infos.append(
+ FileInfo(
+ url=signed_urls[0],
+ checksum=checksum,
+ filename=display_name,
+ file_size=content_length,
+ )
+ )
+
+ return file_infos
+
+ async def save_legacy_file(
+ self, *, organization_id: str, filename: str, fileObj: BinaryIO
+ ) -> tuple[str, str] | None:
+ todays_date = datetime.now(tz=timezone.utc).strftime("%Y-%m-%d")
+ bucket = settings.GCS_BUCKET_UPLOADS
+ storage_class = await self._get_storage_class_for_org(organization_id)
+ tags = await self._get_tags_for_org(organization_id)
+ # First try uploading with original filename
+ try:
+ sanitized_filename = os.path.basename(filename) # Remove any path components
+ gcs_uri = f"gs://{bucket}/{settings.ENV}/{organization_id}/{todays_date}/{sanitized_filename}"
+ uploaded_uri = await self.async_client.upload_file_stream(
+ gcs_uri, fileObj, storage_class=storage_class, tags=tags
+ )
+ except Exception:
+ LOG.error("Failed to upload file to GCS", exc_info=True)
+ uploaded_uri = None
+
+ # If upload fails, try again with UUID prefix
+ if not uploaded_uri:
+ uuid_prefixed_filename = f"{str(uuid.uuid4())}_{filename}"
+ gcs_uri = f"gs://{bucket}/{settings.ENV}/{organization_id}/{todays_date}/{uuid_prefixed_filename}"
+ fileObj.seek(0) # Reset file pointer
+ uploaded_uri = await self.async_client.upload_file_stream(
+ gcs_uri, fileObj, storage_class=storage_class, tags=tags
+ )
+
+ if not uploaded_uri:
+ LOG.error(
+ "Failed to upload file to GCS after retrying with UUID prefix",
+ organization_id=organization_id,
+ storage_class=storage_class,
+ filename=filename,
+ exc_info=True,
+ )
+ return None
+ LOG.debug(
+ "Legacy file upload",
+ organization_id=organization_id,
+ storage_class=storage_class,
+ filename=filename,
+ uploaded_uri=uploaded_uri,
+ )
+ # Generate a signed URL for the uploaded file
+ signed_urls = await self.async_client.create_signed_urls([uploaded_uri])
+ if not signed_urls:
+ LOG.error(
+ "Failed to create signed URL for uploaded file",
+ organization_id=organization_id,
+ storage_class=storage_class,
+ uploaded_uri=uploaded_uri,
+ filename=filename,
+ exc_info=True,
+ )
+ return None
+ return signed_urls[0], uploaded_uri
+
+ def _build_browser_session_uri(
+ self,
+ organization_id: str,
+ browser_session_id: str,
+ artifact_type: str,
+ remote_path: str,
+ date: str | None = None,
+ ) -> str:
+ """Build the GCS URI for a browser session file."""
+ base = f"gs://{self.bucket}/{self._PATH_VERSION}/{settings.ENV}/{organization_id}/browser_sessions/{browser_session_id}/{artifact_type}"
+ if date:
+ return f"{base}/{date}/{remote_path}"
+ return f"{base}/{remote_path}"
+
+ async def sync_browser_session_file(
+ self,
+ organization_id: str,
+ browser_session_id: str,
+ artifact_type: str,
+ local_file_path: str,
+ remote_path: str,
+ date: str | None = None,
+ ) -> str:
+ """Sync a file from local browser session to GCS."""
+ uri = self._build_browser_session_uri(organization_id, browser_session_id, artifact_type, remote_path, date)
+ storage_class = await self._get_storage_class_for_org(organization_id)
+ tags = await self._get_tags_for_org(organization_id)
+ await self.async_client.upload_file_from_path(uri, local_file_path, storage_class=storage_class, tags=tags)
+
+ if artifact_type == "downloads":
+ # See s3.py — DB is the single source of truth for the user-facing
+ # listing and the agent's baseline / complete_on_download checks.
+ # Partials get a row with checksum=None; the row is dropped on
+ # Chrome's atomic-rename ``Change.deleted`` event. Exceptions
+ # propagate so the watcher's bounded retry can recover from a
+ # transient DB outage — both ops are idempotent.
+ is_partial = remote_path.endswith(BROWSER_DOWNLOADING_SUFFIX)
+ checksum = None if is_partial else calculate_sha256_for_file(local_file_path)
+ file_size = None if is_partial else _safe_get_file_size(local_file_path)
+ await app.ARTIFACT_MANAGER.create_browser_session_download_artifact(
+ organization_id=organization_id,
+ browser_session_id=browser_session_id,
+ uri=uri,
+ filename=os.path.basename(remote_path),
+ checksum=checksum,
+ file_size=file_size,
+ )
+ elif artifact_type == "videos":
+ # Recording uploaded once at session close — see s3.py. Artifact-
+ # row creation is best-effort: the only caller swallows
+ # exceptions without retry, so the gated legacy listing fallback
+ # in ``get_shared_recordings_in_browser_session`` is the safety
+ # net for missed writes (when the session has no RECORDING rows
+ # we fall through to the GCS LIST path, so a row-less recording
+ # still surfaces via the legacy signed URL).
+ checksum = calculate_sha256_for_file(local_file_path)
+ file_size = _safe_get_file_size(local_file_path)
+ await app.ARTIFACT_MANAGER.create_browser_session_recording_artifact(
+ organization_id=organization_id,
+ browser_session_id=browser_session_id,
+ uri=uri,
+ filename=os.path.basename(remote_path),
+ checksum=checksum,
+ file_size=file_size,
+ )
+
+ return uri
+
+ async def delete_browser_session_file(
+ self,
+ organization_id: str,
+ browser_session_id: str,
+ artifact_type: str,
+ remote_path: str,
+ date: str | None = None,
+ ) -> None:
+ """Delete a file from browser session storage in GCS.
+
+ For ``downloads``, also drop the matching DOWNLOAD artifact row so a
+ subsequent ``GET /v1/browser_sessions/{id}`` doesn't hand out a signed
+ URL that 404s. Mirrors the S3 implementation.
+ """
+ uri = self._build_browser_session_uri(organization_id, browser_session_id, artifact_type, remote_path, date)
+ if artifact_type == "downloads":
+ try:
+ await app.DATABASE.artifacts.delete_artifact_for_browser_session(
+ organization_id=organization_id,
+ browser_session_id=browser_session_id,
+ uri=uri,
+ artifact_type=ArtifactType.DOWNLOAD,
+ )
+ except Exception:
+ LOG.warning(
+ "Failed to delete browser-session download artifact row; proceeding with GCS delete",
+ organization_id=organization_id,
+ browser_session_id=browser_session_id,
+ remote_path=remote_path,
+ exc_info=True,
+ )
+ await self.async_client.delete_file(uri)
+
+ async def browser_session_file_exists(
+ self,
+ organization_id: str,
+ browser_session_id: str,
+ artifact_type: str,
+ remote_path: str,
+ date: str | None = None,
+ ) -> bool:
+ """Check if a file exists in browser session storage in GCS."""
+ uri = self._build_browser_session_uri(organization_id, browser_session_id, artifact_type, remote_path, date)
+ try:
+ info = await self.async_client.get_object_info(uri)
+ return info is not None
+ except Exception:
+ return False
+
+ def assert_managed_file_access(self, uri: str, organization_id: str) -> None:
+ try:
+ parsed_uri = GcsUri(uri)
+ except Exception as e:
+ raise PermissionError(f"No permission to access storage URI: {uri}") from e
+
+ # Uploads bucket: object paths use {env}/{org}/ or downloads/{env}/{org}/
+ if parsed_uri.bucket == settings.GCS_BUCKET_UPLOADS:
+ allowed_prefixes = (
+ f"{settings.ENV}/{organization_id}/",
+ f"{DOWNLOAD_FILE_PREFIX}/{settings.ENV}/{organization_id}/",
+ )
+ if any(parsed_uri.object_path.startswith(prefix) for prefix in allowed_prefixes):
+ return
+
+ # Artifacts bucket: object paths use v1/{env}/{org}/
+ if parsed_uri.bucket == settings.GCS_BUCKET_ARTIFACTS:
+ artifact_prefix = f"{self._PATH_VERSION}/{settings.ENV}/{organization_id}/"
+ if parsed_uri.object_path.startswith(artifact_prefix):
+ return
+
+ raise PermissionError(f"No permission to access storage URI: {uri}")
+
+ async def download_managed_file(self, uri: str, organization_id: str) -> bytes | None:
+ """Download a managed org-scoped file from GCS."""
+ self.assert_managed_file_access(uri, organization_id)
+ return await self.async_client.download_file(uri, log_exception=False)
+
+ async def file_exists(self, uri: str) -> bool:
+ """Check if a file exists at the given GCS URI."""
+ try:
+ info = await self.async_client.get_object_info(uri)
+ return info is not None
+ except Exception:
+ return False
+
+ @property
+ def storage_type(self) -> str:
+ """Returns 'gcs' as the storage type."""
+ return "gcs"
diff --git a/skyvern/forge/sdk/artifact/storage/test_gcs_storage.py b/skyvern/forge/sdk/artifact/storage/test_gcs_storage.py
new file mode 100644
index 000000000..b586d8fd5
--- /dev/null
+++ b/skyvern/forge/sdk/artifact/storage/test_gcs_storage.py
@@ -0,0 +1,360 @@
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+import skyvern.forge.sdk.api.real_gcp as real_gcp_module
+from skyvern.config import settings
+from skyvern.forge.sdk.api.gcp import STORAGE_CLASS_STANDARD
+from skyvern.forge.sdk.api.real_gcp import RealAsyncGcsStorageClient
+from skyvern.forge.sdk.artifact.models import Artifact, ArtifactType
+from skyvern.forge.sdk.artifact.storage.gcs import GcsStorage
+
+TEST_BUCKET = "test-gcs-bucket"
+TEST_ORGANIZATION_ID = "test-org-123"
+TEST_BROWSER_SESSION_ID = "bs_test_123"
+
+
+def make_artifact(uri: str, artifact_id: str = "a_1") -> Artifact:
+ return Artifact(
+ artifact_id=artifact_id,
+ artifact_type=ArtifactType.SCREENSHOT,
+ uri=uri,
+ organization_id=TEST_ORGANIZATION_ID,
+ created_at=datetime.utcnow(),
+ modified_at=datetime.utcnow(),
+ )
+
+
+class GcsStorageForTests(GcsStorage):
+ """Test subclass that injects a mock client and bypasses real client init."""
+
+ async_client: Any # Allow mock attribute access
+
+ def __init__(self, bucket: str) -> None:
+ # Don't call super().__init__ to avoid creating a real RealAsyncGcsStorageClient
+ self.bucket = bucket
+ self.async_client = AsyncMock()
+
+
+def gcs_storage() -> GcsStorageForTests:
+ return GcsStorageForTests(bucket=TEST_BUCKET)
+
+
[email protected](autouse=True)
+def mock_browser_session_artifact_create(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Stub out the DB-side artifact-row inserts for browser-session files.
+
+ Mirrors the azure/s3 storage test fixtures — the forge app isn't initialized
+ in these storage-only tests, so patch the module-level ``app`` reference.
+ """
+ import skyvern.forge.sdk.artifact.storage.gcs as gcs_module
+
+ fake_app = MagicMock()
+ fake_app.ARTIFACT_MANAGER.create_browser_session_download_artifact = AsyncMock(return_value="a_test")
+ fake_app.ARTIFACT_MANAGER.create_browser_session_recording_artifact = AsyncMock(return_value="a_test")
+ monkeypatch.setattr(gcs_module, "app", fake_app)
+
+
+class TestGcsStorageArtifacts:
+ """Round-trip and URI construction for artifacts."""
+
+ async def test_store_artifact(self, gcs_storage: GcsStorageForTests) -> None:
+ artifact = make_artifact(f"gs://{TEST_BUCKET}/v1/{settings.ENV}/{TEST_ORGANIZATION_ID}/a.png")
+ await gcs_storage.store_artifact(artifact, b"payload")
+ gcs_storage.async_client.upload_file.assert_called_once_with(
+ artifact.uri, b"payload", storage_class=STORAGE_CLASS_STANDARD, tags={}
+ )
+
+ async def test_retrieve_artifact(self, gcs_storage: GcsStorageForTests) -> None:
+ gcs_storage.async_client.download_file.return_value = b"payload"
+ artifact = make_artifact(f"gs://{TEST_BUCKET}/o.png")
+ assert await gcs_storage.retrieve_artifact(artifact) == b"payload"
+
+ async def test_get_share_link(self, gcs_storage: GcsStorageForTests) -> None:
+ gcs_storage.async_client.create_signed_urls.return_value = ["https://signed-url?X-Goog-Signature=abc"]
+ artifact = make_artifact(f"gs://{TEST_BUCKET}/o.png")
+ link = await gcs_storage.get_share_link(artifact)
+ assert link == "https://signed-url?X-Goog-Signature=abc"
+
+
+class TestGcsStorageBrowserSessionFiles:
+ """Browser session file methods."""
+
+ async def test_sync_browser_session_file_with_date(self, gcs_storage: GcsStorageForTests, tmp_path: Path) -> None:
+ test_file = tmp_path / "recording.webm"
+ test_file.write_bytes(b"fake video data")
+
+ uri = await gcs_storage.sync_browser_session_file(
+ organization_id=TEST_ORGANIZATION_ID,
+ browser_session_id=TEST_BROWSER_SESSION_ID,
+ artifact_type="videos",
+ local_file_path=str(test_file),
+ remote_path="recording.webm",
+ date="2025-01-15",
+ )
+
+ expected_uri = f"gs://{TEST_BUCKET}/v1/{settings.ENV}/{TEST_ORGANIZATION_ID}/browser_sessions/{TEST_BROWSER_SESSION_ID}/videos/2025-01-15/recording.webm"
+ assert uri == expected_uri
+ gcs_storage.async_client.upload_file_from_path.assert_called_once()
+
+ async def test_sync_browser_session_file_without_date(
+ self, gcs_storage: GcsStorageForTests, tmp_path: Path
+ ) -> None:
+ test_file = tmp_path / "document.pdf"
+ test_file.write_bytes(b"fake download data")
+
+ uri = await gcs_storage.sync_browser_session_file(
+ organization_id=TEST_ORGANIZATION_ID,
+ browser_session_id=TEST_BROWSER_SESSION_ID,
+ artifact_type="downloads",
+ local_file_path=str(test_file),
+ remote_path="document.pdf",
+ date=None,
+ )
+
+ expected_uri = f"gs://{TEST_BUCKET}/v1/{settings.ENV}/{TEST_ORGANIZATION_ID}/browser_sessions/{TEST_BROWSER_SESSION_ID}/downloads/document.pdf"
+ assert uri == expected_uri
+
+ async def test_browser_session_file_exists_returns_true(self, gcs_storage: GcsStorageForTests) -> None:
+ gcs_storage.async_client.get_object_info.return_value = {"LastModified": "2025-01-15"}
+
+ exists = await gcs_storage.browser_session_file_exists(
+ organization_id=TEST_ORGANIZATION_ID,
+ browser_session_id=TEST_BROWSER_SESSION_ID,
+ artifact_type="videos",
+ remote_path="exists.webm",
+ date="2025-01-15",
+ )
+
+ assert exists is True
+
+ async def test_browser_session_file_exists_returns_false_on_exception(
+ self, gcs_storage: GcsStorageForTests
+ ) -> None:
+ gcs_storage.async_client.get_object_info.side_effect = Exception("Not found")
+
+ exists = await gcs_storage.browser_session_file_exists(
+ organization_id=TEST_ORGANIZATION_ID,
+ browser_session_id=TEST_BROWSER_SESSION_ID,
+ artifact_type="videos",
+ remote_path="nonexistent.webm",
+ date="2025-01-15",
+ )
+
+ assert exists is False
+
+ async def test_delete_browser_session_file(self, gcs_storage: GcsStorageForTests) -> None:
+ await gcs_storage.delete_browser_session_file(
+ organization_id=TEST_ORGANIZATION_ID,
+ browser_session_id=TEST_BROWSER_SESSION_ID,
+ artifact_type="videos",
+ remote_path="to_delete.webm",
+ date="2025-01-15",
+ )
+
+ expected_uri = f"gs://{TEST_BUCKET}/v1/{settings.ENV}/{TEST_ORGANIZATION_ID}/browser_sessions/{TEST_BROWSER_SESSION_ID}/videos/2025-01-15/to_delete.webm"
+ gcs_storage.async_client.delete_file.assert_called_once_with(expected_uri)
+
+ async def test_delete_browser_session_nonexistent_does_not_raise(self, gcs_storage: GcsStorageForTests) -> None:
+ # Mirror the client contract: delete of a missing object is a no-op.
+ gcs_storage.async_client.delete_file.return_value = None
+ await gcs_storage.delete_browser_session(TEST_ORGANIZATION_ID, "wpid_missing")
+ gcs_storage.async_client.delete_file.assert_called_once()
+
+ async def test_file_exists_returns_true(self, gcs_storage: GcsStorageForTests) -> None:
+ gcs_storage.async_client.get_object_info.return_value = {"LastModified": "2025-01-15"}
+ uri = f"gs://{TEST_BUCKET}/test/file.txt"
+
+ assert await gcs_storage.file_exists(uri) is True
+
+ async def test_file_exists_returns_false_on_exception(self, gcs_storage: GcsStorageForTests) -> None:
+ gcs_storage.async_client.get_object_info.side_effect = Exception("Not found")
+ uri = f"gs://{TEST_BUCKET}/nonexistent/file.txt"
+
+ assert await gcs_storage.file_exists(uri) is False
+
+ async def test_assert_managed_file_access_accepts_org_scoped_uploads(self, gcs_storage: GcsStorageForTests) -> None:
+ legacy_uri = f"gs://{settings.GCS_BUCKET_UPLOADS}/{settings.ENV}/{TEST_ORGANIZATION_ID}/file.pdf"
+ downloads_uri = (
+ f"gs://{settings.GCS_BUCKET_UPLOADS}/downloads/{settings.ENV}/{TEST_ORGANIZATION_ID}/wr_123/file.pdf"
+ )
+
+ gcs_storage.assert_managed_file_access(legacy_uri, TEST_ORGANIZATION_ID)
+ gcs_storage.assert_managed_file_access(downloads_uri, TEST_ORGANIZATION_ID)
+
+ async def test_assert_managed_file_access_accepts_artifact_bucket(self, gcs_storage: GcsStorageForTests) -> None:
+ artifact_uri = (
+ f"gs://{settings.GCS_BUCKET_ARTIFACTS}/v1/{settings.ENV}/{TEST_ORGANIZATION_ID}/"
+ "workflow_runs/wr_123/wrb_456/2026-03-23T17:57:58.370827_a_789_pdf.pdf"
+ )
+ gcs_storage.assert_managed_file_access(artifact_uri, TEST_ORGANIZATION_ID)
+
+ async def test_assert_managed_file_access_rejects_other_org(self, gcs_storage: GcsStorageForTests) -> None:
+ uri = f"gs://{settings.GCS_BUCKET_UPLOADS}/{settings.ENV}/o_other/file.pdf"
+ with pytest.raises(PermissionError, match="No permission to access storage URI"):
+ gcs_storage.assert_managed_file_access(uri, TEST_ORGANIZATION_ID)
+
+ async def test_assert_managed_file_access_rejects_other_org_artifact_bucket(
+ self, gcs_storage: GcsStorageForTests
+ ) -> None:
+ uri = (
+ f"gs://{settings.GCS_BUCKET_ARTIFACTS}/v1/{settings.ENV}/o_other/workflow_runs/wr_123/wrb_456/artifact.pdf"
+ )
+ with pytest.raises(PermissionError, match="No permission to access storage URI"):
+ gcs_storage.assert_managed_file_access(uri, TEST_ORGANIZATION_ID)
+
+ async def test_download_managed_file(self, gcs_storage: GcsStorageForTests) -> None:
+ test_data = b"uploaded file content"
+ gcs_storage.async_client.download_file.return_value = test_data
+ uri = f"gs://{settings.GCS_BUCKET_UPLOADS}/{settings.ENV}/{TEST_ORGANIZATION_ID}/file.pdf"
+
+ downloaded = await gcs_storage.download_managed_file(uri, TEST_ORGANIZATION_ID)
+
+ assert downloaded == test_data
+ gcs_storage.async_client.download_file.assert_called_once_with(uri, log_exception=False)
+
+ async def test_download_managed_file_returns_none(self, gcs_storage: GcsStorageForTests) -> None:
+ gcs_storage.async_client.download_file.return_value = None
+ uri = f"gs://{settings.GCS_BUCKET_UPLOADS}/{settings.ENV}/{TEST_ORGANIZATION_ID}/nonexistent/file.txt"
+
+ assert await gcs_storage.download_managed_file(uri, TEST_ORGANIZATION_ID) is None
+
+ async def test_download_managed_file_rejects_other_org(self, gcs_storage: GcsStorageForTests) -> None:
+ uri = f"gs://{settings.GCS_BUCKET_UPLOADS}/{settings.ENV}/o_other/file.pdf"
+ with pytest.raises(PermissionError, match="No permission to access storage URI"):
+ await gcs_storage.download_managed_file(uri, TEST_ORGANIZATION_ID)
+
+ async def test_storage_type_property(self, gcs_storage: GcsStorageForTests) -> None:
+ assert gcs_storage.storage_type == "gcs"
+
+
+class TestGcsStorageBuildUri:
+ """GCS URI building methods (sync)."""
+
+ def test_build_base_uri(self, gcs_storage: GcsStorageForTests) -> None:
+ base = gcs_storage._build_base_uri(TEST_ORGANIZATION_ID)
+ assert base == f"gs://{TEST_BUCKET}/v1/{settings.ENV}/{TEST_ORGANIZATION_ID}"
+
+ def test_build_browser_session_uri_with_date(self, gcs_storage: GcsStorageForTests) -> None:
+ uri = gcs_storage._build_browser_session_uri(
+ organization_id=TEST_ORGANIZATION_ID,
+ browser_session_id=TEST_BROWSER_SESSION_ID,
+ artifact_type="videos",
+ remote_path="file.webm",
+ date="2025-01-15",
+ )
+ expected = f"gs://{TEST_BUCKET}/v1/{settings.ENV}/{TEST_ORGANIZATION_ID}/browser_sessions/{TEST_BROWSER_SESSION_ID}/videos/2025-01-15/file.webm"
+ assert uri == expected
+
+ def test_build_browser_session_uri_without_date(self, gcs_storage: GcsStorageForTests) -> None:
+ uri = gcs_storage._build_browser_session_uri(
+ organization_id=TEST_ORGANIZATION_ID,
+ browser_session_id=TEST_BROWSER_SESSION_ID,
+ artifact_type="downloads",
+ remote_path="file.pdf",
+ date=None,
+ )
+ expected = f"gs://{TEST_BUCKET}/v1/{settings.ENV}/{TEST_ORGANIZATION_ID}/browser_sessions/{TEST_BROWSER_SESSION_ID}/downloads/file.pdf"
+ assert uri == expected
+
+
+GCS_CONTENT_TYPE_TEST_CASES = [
+ ("video.webm", "video/webm"),
+ ("data.json", "application/json"),
+ ("network.har", "application/json"),
+ ("screenshot.png", "image/png"),
+ ("output.txt", "text/plain"),
+ ("debug.log", "text/plain"),
+]
+
+
+class TestGcsStorageClientContentType:
+ """RealAsyncGcsStorageClient sets the correct content type by extension."""
+
+ @pytest.mark.parametrize("filename,expected_content_type", GCS_CONTENT_TYPE_TEST_CASES)
+ async def test_content_type_guessing(self, tmp_path: Path, filename: str, expected_content_type: str) -> None:
+ test_file = tmp_path / filename
+ test_file.write_bytes(b"test content")
+
+ with patch.object(RealAsyncGcsStorageClient, "_get_client") as mock_get_client:
+ mock_blob = MagicMock()
+ mock_bucket = MagicMock()
+ mock_bucket.blob.return_value = mock_blob
+ mock_client = MagicMock()
+ mock_client.bucket.return_value = mock_bucket
+ mock_get_client.return_value = mock_client
+
+ client = RealAsyncGcsStorageClient(project_id="test")
+ await client.upload_file_from_path(uri=f"gs://test-bucket/path/{filename}", file_path=str(test_file))
+
+ call_kwargs = mock_blob.upload_from_filename.call_args.kwargs
+ assert call_kwargs["content_type"] == expected_content_type
+
+
+class TestGcsStorageClientSigning:
+ """V4 signed-URL generation and Workload-Identity signBlob routing."""
+
+ def test_create_signed_url_uses_v4_local(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(settings, "GCS_SIGNER_SA_EMAIL", None)
+ with patch.object(RealAsyncGcsStorageClient, "_get_blob") as mock_get_blob:
+ mock_blob = MagicMock()
+ mock_blob.generate_signed_url.return_value = "https://signed?X-Goog-Signature=abc&X-Goog-Algorithm=GOOG4"
+ mock_get_blob.return_value = mock_blob
+
+ client = RealAsyncGcsStorageClient(project_id="test")
+ url = client._create_signed_url("gs://b/o.txt", expiry_hours=1)
+
+ assert url is not None and "X-Goog-Signature" in url
+ kwargs = mock_blob.generate_signed_url.call_args.kwargs
+ assert kwargs["version"] == "v4"
+ assert kwargs["method"] == "GET"
+ # Local key signing — no IAM signBlob params.
+ assert "service_account_email" not in kwargs
+ assert "access_token" not in kwargs
+
+ def test_signing_under_workload_identity(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(settings, "GCS_SIGNER_SA_EMAIL", "[email protected]")
+ fake_creds = MagicMock()
+ fake_creds.token = "tok123"
+ monkeypatch.setattr(real_gcp_module, "google_auth_default", lambda scopes=None: (fake_creds, "proj"))
+
+ with patch.object(RealAsyncGcsStorageClient, "_get_blob") as mock_get_blob:
+ mock_blob = MagicMock()
+ mock_blob.generate_signed_url.return_value = "https://signed"
+ mock_get_blob.return_value = mock_blob
+
+ client = RealAsyncGcsStorageClient(project_id="test")
+ client._create_signed_url("gs://b/o.txt")
+
+ kwargs = mock_blob.generate_signed_url.call_args.kwargs
+ assert kwargs["service_account_email"] == "[email protected]"
+ assert kwargs["access_token"] == "tok123"
+ fake_creds.refresh.assert_called_once()
+
+ @pytest.mark.asyncio
+ async def test_batch_signing_refreshes_token_once(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ # Under Workload Identity, signing a batch must mint the IAM token once,
+ # not once per URL.
+ monkeypatch.setattr(settings, "GCS_SIGNER_SA_EMAIL", "[email protected]")
+ fake_creds = MagicMock()
+ fake_creds.token = "tok123"
+ monkeypatch.setattr(real_gcp_module, "google_auth_default", lambda scopes=None: (fake_creds, "proj"))
+
+ with patch.object(RealAsyncGcsStorageClient, "_get_blob") as mock_get_blob:
+ mock_blob = MagicMock()
+ mock_blob.generate_signed_url.return_value = "https://signed"
+ mock_get_blob.return_value = mock_blob
+
+ client = RealAsyncGcsStorageClient(project_id="test")
+ urls = await client.create_signed_urls(["gs://b/a.txt", "gs://b/b.txt", "gs://b/c.txt"])
+
+ assert urls is not None and len(urls) == 3
+ fake_creds.refresh.assert_called_once()
+ assert mock_blob.generate_signed_url.call_count == 3
diff --git a/uv.lock b/uv.lock
index 1b7c17dee..3a6230b82 100644
--- a/uv.lock
+++ b/uv.lock
@@ -5752,6 +5752,7 @@ local = [
{ name = "google-auth" },
{ name = "google-auth-oauthlib" },
{ name = "google-cloud-aiplatform" },
+ { name = "google-cloud-storage" },
{ name = "greenlet", version = "3.0.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" },
{ name = "greenlet", version = "3.4.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
{ name = "jinja2" },
@@ -5814,6 +5815,7 @@ server = [
{ name = "google-auth" },
{ name = "google-auth-oauthlib" },
{ name = "google-cloud-aiplatform" },
+ { name = "google-cloud-storage" },
{ name = "greenlet", version = "3.0.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" },
{ name = "greenlet", version = "3.4.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
{ name = "jinja2" },
@@ -5960,6 +5962,8 @@ requires-dist = [
{ name = "google-auth-oauthlib", marker = "extra == 'server'", specifier = ">=1.3.1,<2" },
{ name = "google-cloud-aiplatform", marker = "extra == 'local'", specifier = ">=1.149.0,<2" },
{ name = "google-cloud-aiplatform", marker = "extra == 'server'", specifier = ">=1.149.0,<2" },
+ { name = "google-cloud-storage", marker = "extra == 'local'", specifier = ">=2.18,<4" },
+ { name = "google-cloud-storage", marker = "extra == 'server'", specifier = ">=2.18,<4" },
{ name = "greenlet", marker = "python_full_version == '3.11.*' and extra == 'local'", specifier = "==3.0.3" },
{ name = "greenlet", marker = "python_full_version == '3.11.*' and extra == 'server'", specifier = "==3.0.3" },
{ name = "greenlet", marker = "python_full_version >= '3.12' and python_full_version < '3.14' and extra == 'local'", specifier = ">3.0.3" },