Skip to content

Drop in a screenshot and convert it to clean code (HTML/Tailwind/React/Vue)

Python

Add uploaded asset persistence tool

Abi Rajaff1509d4a31d
diff --git a/.gitignore b/.gitignore
index d9af67e0..d5545220 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,7 @@ node_modules
# Run logs
backend/run_logs/*
+backend/local_assets/*
# Weird Docker setup related files
backend/backend/*
diff --git a/backend/agent/tools/definitions.py b/backend/agent/tools/definitions.py
index c6af1f8d..1b796aac 100644
--- a/backend/agent/tools/definitions.py
+++ b/backend/agent/tools/definitions.py
@@ -1,6 +1,7 @@
from typing import Any, Dict, List
from agent.tools.types import CanonicalToolDefinition
+from uploaded_assets.tools import SAVE_ASSETS_TOOL_DEFINITION
def _create_schema() -> Dict[str, Any]:
@@ -145,6 +146,7 @@ def canonical_tool_definitions(
),
parameters=_remove_background_schema(),
),
+ SAVE_ASSETS_TOOL_DEFINITION,
CanonicalToolDefinition(
name="retrieve_option",
description=(
diff --git a/backend/agent/tools/runtime.py b/backend/agent/tools/runtime.py
index 33e5d487..a890162c 100644
--- a/backend/agent/tools/runtime.py
+++ b/backend/agent/tools/runtime.py
@@ -7,6 +7,7 @@ from codegen.utils import extract_html_content
from config import REPLICATE_API_KEY
from image_generation.generation import process_tasks
from image_generation.replicate import remove_background
+from uploaded_assets.tools import run_save_assets
from agent.state import AgentFileState, ensure_str
from agent.tools.types import ToolCall, ToolExecutionResult
@@ -48,6 +49,8 @@ class AgentToolRuntime:
return await self._generate_images(tool_call.arguments)
if tool_call.name == "remove_background":
return await self._remove_background(tool_call.arguments)
+ if tool_call.name == "save_assets":
+ return run_save_assets(tool_call.arguments)
if tool_call.name == "retrieve_option":
return self._retrieve_option(tool_call.arguments)
return ToolExecutionResult(
diff --git a/backend/agent/tools/summaries.py b/backend/agent/tools/summaries.py
index c87ba88e..bee522e6 100644
--- a/backend/agent/tools/summaries.py
+++ b/backend/agent/tools/summaries.py
@@ -3,6 +3,7 @@ from typing import Any, Dict
from agent.state import AgentFileState, ensure_str
from agent.tools.types import ToolCall
+from uploaded_assets.tools import summarize_save_assets_input
def summarize_text(value: str, limit: int = 240) -> str:
@@ -63,6 +64,9 @@ def summarize_tool_input(tool_call: ToolCall, file_state: AgentFileState) -> Dic
}
return {"image_urls": []}
+ if tool_call.name == "save_assets":
+ return summarize_save_assets_input(args)
+
if tool_call.name == "retrieve_option":
return {
"option_number": args.get("option_number"),
diff --git a/backend/config.py b/backend/config.py
index 5ac65571..cb753b31 100644
--- a/backend/config.py
+++ b/backend/config.py
@@ -15,6 +15,9 @@ REPLICATE_API_KEY = os.environ.get("REPLICATE_API_KEY", None)
# Debugging-related
IS_DEBUG_ENABLED = bool(os.environ.get("IS_DEBUG_ENABLED", False))
DEBUG_DIR = os.environ.get("DEBUG_DIR", "")
+LOCAL_ASSET_DIR = os.environ.get(
+ "LOCAL_ASSET_DIR", os.path.join(os.path.dirname(__file__), "local_assets")
+)
# Set to True when running in production (on the hosted version)
# Used as a feature flag to enable or disable certain features
diff --git a/backend/main.py b/backend/main.py
index 20d7d062..0f8109eb 100644
--- a/backend/main.py
+++ b/backend/main.py
@@ -8,8 +8,10 @@ from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from config import IS_DEBUG_ENABLED
from routes import screenshot, generate_code, home, evals, export, design_systems
+from uploaded_assets import configure_uploaded_asset_routes
app = FastAPI(openapi_url=None, docs_url=None, redoc_url=None)
+configure_uploaded_asset_routes(app)
@app.on_event("startup")
diff --git a/backend/routes/generate_code.py b/backend/routes/generate_code.py
index c988fd16..493783e7 100644
--- a/backend/routes/generate_code.py
+++ b/backend/routes/generate_code.py
@@ -53,6 +53,11 @@ MessageType = Literal[
from prompts.pipeline import build_prompt_messages
from prompts.request_parsing import parse_prompt_content, parse_prompt_history
from prompts.prompt_types import PromptHistoryMessage, Stack, UserTurnInput
+from uploaded_assets import (
+ append_uploaded_asset_ids_to_history,
+ append_uploaded_asset_ids_to_prompt,
+ infer_local_asset_base_url,
+)
from agent.runner import Agent
from routes.model_choice_sets import (
ALL_KEYS_MODELS_DEFAULT,
@@ -242,8 +247,13 @@ class ExtractedParams:
class ParameterExtractionStage:
"""Handles parameter extraction and validation from WebSocket requests"""
- def __init__(self, throw_error: Callable[[str], Coroutine[Any, Any, None]]):
+ def __init__(
+ self,
+ throw_error: Callable[[str], Coroutine[Any, Any, None]],
+ asset_base_url: str = "",
+ ):
self.throw_error = throw_error
+ self.asset_base_url = asset_base_url
async def extract_and_validate(self, params: Dict[str, Any]) -> ExtractedParams:
"""Extract and validate all parameters from the request"""
@@ -303,6 +313,9 @@ class ParameterExtractionStage:
params.get("history")
)
+ prompt = append_uploaded_asset_ids_to_prompt(prompt, self.asset_base_url)
+ history = append_uploaded_asset_ids_to_history(history, self.asset_base_url)
+
# Extract file state for agent edits
raw_file_state = params.get("fileState")
file_state: Dict[str, str] | None = None
@@ -669,7 +682,10 @@ class ParameterExtractionMiddleware(Middleware):
context.params = await context.ws_comm.receive_params()
# Extract and validate
- param_extractor = ParameterExtractionStage(context.throw_error)
+ param_extractor = ParameterExtractionStage(
+ context.throw_error,
+ infer_local_asset_base_url(context.websocket),
+ )
context.extracted_params = await param_extractor.extract_and_validate(
context.params
)
diff --git a/backend/tests/test_agent_tool_runtime.py b/backend/tests/test_agent_tool_runtime.py
index 247dfeb9..825de183 100644
--- a/backend/tests/test_agent_tool_runtime.py
+++ b/backend/tests/test_agent_tool_runtime.py
@@ -1,8 +1,17 @@
+import base64
+from pathlib import Path
+
import pytest
from agent.state import AgentFileState
from agent.tools.runtime import AgentToolRuntime
from agent.tools.types import ToolCall
+from uploaded_assets import persist_data_url_as_temporary_asset
+
+
+def _data_url(payload: bytes, content_type: str = "image/png") -> str:
+ encoded = base64.b64encode(payload).decode("ascii")
+ return f"data:{content_type};base64,{encoded}"
def test_edit_file_returns_structured_result_with_diff() -> None:
@@ -58,3 +67,46 @@ async def test_execute_edit_file_uses_updated_result_shape() -> None:
assert result.result["content"] == "Successfully edited file at index.html."
assert set(result.result["details"].keys()) == {"diff", "firstChangedLine"}
assert "--- index.html" in result.result["details"]["diff"]
+
+
+async def test_save_assets_promotes_temporary_asset_id(
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+) -> None:
+ temp_dir = tmp_path / "tmp-assets"
+ asset_dir = tmp_path / "local-assets"
+ monkeypatch.setattr("uploaded_assets.store.TEMP_ASSET_DIR", str(temp_dir))
+ monkeypatch.setattr("uploaded_assets.store.LOCAL_ASSET_DIR", str(asset_dir))
+
+ temp_asset = persist_data_url_as_temporary_asset(
+ _data_url(b"image-bytes"),
+ "http://127.0.0.1:7001",
+ )
+ assert temp_asset is not None
+
+ runtime = AgentToolRuntime(
+ file_state=AgentFileState(),
+ should_generate_images=False,
+ openai_api_key=None,
+ openai_base_url=None,
+ )
+
+ result = await runtime.execute(
+ ToolCall(
+ id="call-1",
+ name="save_assets",
+ arguments={"asset_ids": [temp_asset.asset_id]},
+ )
+ )
+
+ assert result.ok is True
+ images = result.result["images"]
+ assert len(images) == 1
+ assert images[0]["asset_id"] == temp_asset.asset_id
+ assert images[0]["status"] == "ok"
+ assert images[0]["public_url"].startswith(
+ "http://127.0.0.1:7001/local-assets/"
+ )
+ assert temp_asset.asset_id not in images[0]["public_url"]
+ assert len(list(asset_dir.iterdir())) == 1
diff --git a/backend/tests/test_agent_tools.py b/backend/tests/test_agent_tools.py
index 20b47b14..c972f57b 100644
--- a/backend/tests/test_agent_tools.py
+++ b/backend/tests/test_agent_tools.py
@@ -1,4 +1,6 @@
-from agent.tools import canonical_tool_definitions
+from agent.state import AgentFileState
+from agent.tools import canonical_tool_definitions, summarize_tool_input
+from agent.tools.types import ToolCall
def test_canonical_tool_definitions_include_generate_images_when_enabled() -> None:
@@ -18,3 +20,28 @@ def test_edit_file_tool_description_matches_runtime_output_shape() -> None:
assert "success message" in edit_tool.description
assert "unified diff" in edit_tool.description
+
+
+def test_canonical_tool_definitions_include_save_assets() -> None:
+ tools = canonical_tool_definitions(True)
+ tool_names = [tool.name for tool in tools]
+ assert "save_assets" in tool_names
+ save_assets_tool = next(tool for tool in tools if tool.name == "save_assets")
+ assert save_assets_tool.parameters["required"] == ["asset_ids"]
+ assert save_assets_tool.parameters["properties"]["asset_ids"]["type"] == "array"
+
+
+def test_save_assets_tool_input_summary_uses_asset_ids() -> None:
+ summary = summarize_tool_input(
+ ToolCall(
+ id="call-1",
+ name="save_assets",
+ arguments={"asset_ids": ["asset_one", "asset_two"]},
+ ),
+ AgentFileState(),
+ )
+
+ assert summary == {
+ "count": 2,
+ "asset_ids": ["asset_one", "asset_two"],
+ }
diff --git a/backend/tests/test_prompts.py b/backend/tests/test_prompts.py
index cd024f1a..6c465ed6 100644
--- a/backend/tests/test_prompts.py
+++ b/backend/tests/test_prompts.py
@@ -127,7 +127,7 @@ class TestCreatePrompt:
text = text_part.get("text")
assert isinstance(text, str)
- assert "Reusable design system" in text
+ assert "## Design system" in text
assert "Reuse .mockup-frame" in text
def test_plan_update_with_history_uses_history_strategy(self) -> None:
diff --git a/backend/tests/test_uploaded_assets.py b/backend/tests/test_uploaded_assets.py
new file mode 100644
index 00000000..21cea6bd
--- /dev/null
+++ b/backend/tests/test_uploaded_assets.py
@@ -0,0 +1,80 @@
+import base64
+from pathlib import Path
+
+from uploaded_assets import (
+ append_uploaded_asset_ids_to_prompt,
+ persist_data_url_as_temporary_asset,
+ promote_temporary_asset_id,
+)
+
+
+def _data_url(payload: bytes, content_type: str = "image/png") -> str:
+ encoded = base64.b64encode(payload).decode("ascii")
+ return f"data:{content_type};base64,{encoded}"
+
+
+def test_persist_data_url_as_temporary_asset_writes_tmp_file_and_returns_asset_id(
+ monkeypatch,
+ tmp_path: Path,
+) -> None:
+ temp_dir = tmp_path / "tmp-assets"
+ monkeypatch.setattr("uploaded_assets.store.TEMP_ASSET_DIR", str(temp_dir))
+
+ asset = persist_data_url_as_temporary_asset(
+ _data_url(b"image-bytes"),
+ "http://127.0.0.1:7001",
+ )
+
+ assert asset is not None
+ assert asset.asset_id.startswith("tmp_asset_")
+ assert "/" not in asset.asset_id
+ assert asset.content_type == "image/png"
+ assert len(list(temp_dir.iterdir())) == 2
+
+
+def test_promote_temporary_asset_id_returns_permanent_url(
+ monkeypatch,
+ tmp_path: Path,
+) -> None:
+ temp_dir = tmp_path / "tmp-assets"
+ asset_dir = tmp_path / "local-assets"
+ monkeypatch.setattr("uploaded_assets.store.TEMP_ASSET_DIR", str(temp_dir))
+ monkeypatch.setattr("uploaded_assets.store.LOCAL_ASSET_DIR", str(asset_dir))
+
+ temp_asset = persist_data_url_as_temporary_asset(
+ _data_url(b"image-bytes"),
+ "http://127.0.0.1:7001",
+ )
+ assert temp_asset is not None
+
+ permanent_asset = promote_temporary_asset_id(temp_asset.asset_id)
+
+ assert permanent_asset is not None
+ assert permanent_asset.asset_id == temp_asset.asset_id
+ assert permanent_asset.public_url.startswith(
+ "http://127.0.0.1:7001/local-assets/"
+ )
+ assert temp_asset.asset_id not in permanent_asset.public_url
+ assert len(list(asset_dir.iterdir())) == 1
+
+
+def test_append_uploaded_asset_ids_to_prompt_keeps_image_and_adds_id(
+ monkeypatch,
+ tmp_path: Path,
+) -> None:
+ image = _data_url(b"asset-image")
+ monkeypatch.setattr("uploaded_assets.store.TEMP_ASSET_DIR", str(tmp_path))
+
+ prompt = append_uploaded_asset_ids_to_prompt(
+ {"text": "Build a shop", "images": [image], "videos": []},
+ "http://127.0.0.1:7001",
+ )
+
+ assert prompt["images"] == [image]
+ assert "Uploaded image asset IDs" in prompt["text"]
+ assert "asset_id `tmp_asset_" in prompt["text"]
+ assert "tmp-assets" not in prompt["text"]
+ assert "http://127.0.0.1:7001" not in prompt["text"]
+ assert "save_assets" in prompt["text"]
+ assert "asset_ids list" in prompt["text"]
+ assert "Decide" in prompt["text"]
diff --git a/backend/uploaded_assets/__init__.py b/backend/uploaded_assets/__init__.py
new file mode 100644
index 00000000..0e08e567
--- /dev/null
+++ b/backend/uploaded_assets/__init__.py
@@ -0,0 +1,23 @@
+from uploaded_assets.prompts import (
+ append_uploaded_asset_ids_to_history,
+ append_uploaded_asset_ids_to_prompt,
+)
+from uploaded_assets.store import (
+ SavedAsset,
+ TemporaryAsset,
+ configure_uploaded_asset_routes,
+ infer_local_asset_base_url,
+ persist_data_url_as_temporary_asset,
+ promote_temporary_asset_id,
+)
+
+__all__ = [
+ "SavedAsset",
+ "TemporaryAsset",
+ "append_uploaded_asset_ids_to_history",
+ "append_uploaded_asset_ids_to_prompt",
+ "configure_uploaded_asset_routes",
+ "infer_local_asset_base_url",
+ "persist_data_url_as_temporary_asset",
+ "promote_temporary_asset_id",
+]
diff --git a/backend/uploaded_assets/prompts.py b/backend/uploaded_assets/prompts.py
new file mode 100644
index 00000000..2e91d4ee
--- /dev/null
+++ b/backend/uploaded_assets/prompts.py
@@ -0,0 +1,63 @@
+from copy import deepcopy
+
+from prompts.prompt_types import PromptHistoryMessage, UserTurnInput
+from uploaded_assets.store import persist_data_url_as_temporary_asset
+
+
+def _build_asset_id_block(images: list[str], asset_base_url: str) -> str:
+ asset_lines: list[str] = []
+ for index, image in enumerate(images, start=1):
+ asset = persist_data_url_as_temporary_asset(image, asset_base_url)
+ if asset:
+ asset_lines.append(f"- Image {index}: asset_id `{asset.asset_id}`")
+
+ if not asset_lines:
+ return ""
+
+ joined_asset_lines = "\n".join(asset_lines)
+ return f"""
+
+## Uploaded image asset IDs
+
+The uploaded images in this turn are available to the save_assets tool by
+opaque asset IDs:
+
+{joined_asset_lines}
+
+Some uploaded images may be reference screenshots, while others may be assets
+such as logos, product photos, icons, backgrounds, or illustrations. Decide
+which uploaded images should be used as assets in the generated code.
+
+If you decide one or more uploaded images should be used as assets, call
+save_assets with their asset IDs in the asset_ids list before writing or editing
+code, then use the returned permanent public_url values in the code. Do not
+embed asset IDs, temporary paths, or temporary URLs in the final code. Do not use
+screenshots or reference UI images as page assets unless the user clearly
+intends that. If you decide to use some uploaded images as assets, in your final message
+make sure to mention that concisely.
+"""
+
+
+def append_uploaded_asset_ids_to_prompt(
+ prompt: UserTurnInput,
+ asset_base_url: str,
+) -> UserTurnInput:
+ prompt_with_assets = deepcopy(prompt)
+ block = _build_asset_id_block(prompt_with_assets.get("images", []), asset_base_url)
+ if block:
+ prompt_with_assets["text"] = f"{prompt_with_assets.get('text', '')}\n\n{block}".strip()
+ return prompt_with_assets
+
+
+def append_uploaded_asset_ids_to_history(
+ history: list[PromptHistoryMessage],
+ asset_base_url: str,
+) -> list[PromptHistoryMessage]:
+ history_with_assets = deepcopy(history)
+ for item in history_with_assets:
+ if item["role"] != "user":
+ continue
+ block = _build_asset_id_block(item.get("images", []), asset_base_url)
+ if block:
+ item["text"] = f"{item.get('text', '')}\n\n{block}".strip()
+ return history_with_assets
diff --git a/backend/uploaded_assets/store.py b/backend/uploaded_assets/store.py
new file mode 100644
index 00000000..5cda9ecf
--- /dev/null
+++ b/backend/uploaded_assets/store.py
@@ -0,0 +1,209 @@
+import base64
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass
+from typing import Any, cast
+
+from fastapi import FastAPI, WebSocket
+from fastapi.staticfiles import StaticFiles
+
+from config import LOCAL_ASSET_DIR
+
+
+MAX_UPLOADED_ASSET_BYTES = 20 * 1024 * 1024
+TEMP_ASSET_DIR = os.path.join(tempfile.gettempdir(), "screenshot-to-code-assets")
+SUPPORTED_IMAGE_TYPES = {
+ "image/gif": ".gif",
+ "image/jpeg": ".jpg",
+ "image/png": ".png",
+ "image/webp": ".webp",
+}
+
+
+@dataclass(frozen=True)
+class TemporaryAsset:
+ asset_id: str
+ content_type: str
+
+
+@dataclass(frozen=True)
+class SavedAsset:
+ asset_id: str
+ public_url: str
+ content_type: str
+
+
+def configure_uploaded_asset_routes(app: FastAPI) -> None:
+ os.makedirs(LOCAL_ASSET_DIR, exist_ok=True)
+ app.mount("/local-assets", StaticFiles(directory=LOCAL_ASSET_DIR), name="local-assets")
+
+
+def infer_local_asset_base_url(websocket: WebSocket) -> str:
+ forwarded_host = websocket.headers.get("x-forwarded-host")
+ host = (forwarded_host or websocket.headers.get("host") or "").split(",", 1)[0]
+ host = host.strip()
+
+ forwarded_proto = websocket.headers.get("x-forwarded-proto")
+ raw_scheme = (forwarded_proto or websocket.url.scheme).split(",", 1)[0].strip()
+ scheme = "https" if raw_scheme == "wss" else "http" if raw_scheme == "ws" else raw_scheme
+
+ if not host:
+ host = websocket.url.netloc
+ if not scheme:
+ scheme = "http"
+
+ return f"{scheme}://{host}"
+
+
+def _asset_url(base_url: str, route: str, filename: str) -> str:
+ return f"{base_url.rstrip('/')}/{route}/{filename}"
+
+
+def _digest_for_bytes(image_bytes: bytes) -> str:
+ return hashlib.sha256(image_bytes).hexdigest()[:24]
+
+
+def _asset_id_for_digest(digest: str) -> str:
+ return f"tmp_asset_{digest}"
+
+
+def _digest_for_asset_id(asset_id: str) -> str | None:
+ if not asset_id.startswith("tmp_asset_"):
+ return None
+
+ digest = asset_id.removeprefix("tmp_asset_")
+ if len(digest) != 24 or not all(c in "0123456789abcdef" for c in digest):
+ return None
+
+ return digest
+
+
+def _content_type_for_extension(extension: str) -> str:
+ return next(
+ (
+ candidate_type
+ for candidate_type, candidate_extension in SUPPORTED_IMAGE_TYPES.items()
+ if candidate_extension == extension
+ ),
+ "application/octet-stream",
+ )
+
+
+def _metadata_path(asset_id: str) -> str:
+ return os.path.join(TEMP_ASSET_DIR, f"{asset_id}.json")
+
+
+def _write_metadata(asset_id: str, content_type: str, asset_base_url: str) -> None:
+ with open(_metadata_path(asset_id), "w") as file:
+ json.dump(
+ {
+ "asset_id": asset_id,
+ "content_type": content_type,
+ "asset_base_url": asset_base_url,
+ },
+ file,
+ )
+
+
+def _read_metadata(asset_id: str) -> dict[str, str] | None:
+ try:
+ with open(_metadata_path(asset_id), "r") as file:
+ raw_metadata: Any = json.load(file)
+ except (FileNotFoundError, json.JSONDecodeError):
+ return None
+
+ if not isinstance(raw_metadata, dict):
+ return None
+
+ typed_metadata = cast(dict[str, object], raw_metadata)
+ metadata: dict[str, str] = {}
+ for key in ("content_type", "asset_base_url"):
+ value = typed_metadata.get(key)
+ if isinstance(value, str):
+ metadata[key] = value
+ return metadata
+
+
+def _temporary_asset_path(asset_id: str) -> tuple[str, str, str, str] | None:
+ if not _digest_for_asset_id(asset_id):
+ return None
+
+ metadata = _read_metadata(asset_id)
+ if not metadata:
+ return None
+
+ for extension in SUPPORTED_IMAGE_TYPES.values():
+ filename = f"{asset_id}{extension}"
+ filepath = os.path.join(TEMP_ASSET_DIR, filename)
+ if os.path.isfile(filepath):
+ return (
+ filepath,
+ filename,
+ metadata.get("content_type") or _content_type_for_extension(extension),
+ metadata.get("asset_base_url") or "",
+ )
+ return None
+
+
+def persist_data_url_as_temporary_asset(
+ data_url: str,
+ asset_base_url: str,
+) -> TemporaryAsset | None:
+ if not data_url.startswith("data:image/") or "," not in data_url:
+ return None
+
+ header, encoded = data_url.split(",", 1)
+ content_type = header.removeprefix("data:").split(";", 1)[0].lower()
+ extension = SUPPORTED_IMAGE_TYPES.get(content_type)
+ if not extension:
+ return None
+
+ try:
+ image_bytes = base64.b64decode(encoded, validate=True)
+ except ValueError:
+ return None
+
+ if len(image_bytes) > MAX_UPLOADED_ASSET_BYTES:
+ return None
+
+ os.makedirs(TEMP_ASSET_DIR, exist_ok=True)
+ digest = _digest_for_bytes(image_bytes)
+ asset_id = _asset_id_for_digest(digest)
+ filename = f"{asset_id}{extension}"
+ filepath = os.path.join(TEMP_ASSET_DIR, filename)
+ if not os.path.exists(filepath):
+ with open(filepath, "wb") as file:
+ file.write(image_bytes)
+ _write_metadata(asset_id, content_type, asset_base_url)
+
+ return TemporaryAsset(
+ asset_id=asset_id,
+ content_type=content_type,
+ )
+
+
+def promote_temporary_asset_id(asset_id: str) -> SavedAsset | None:
+ temporary_asset = _temporary_asset_path(asset_id)
+ if not temporary_asset:
+ return None
+
+ source_path, temporary_filename, content_type, asset_base_url = temporary_asset
+ _, extension = os.path.splitext(temporary_filename)
+ digest = _digest_for_asset_id(asset_id)
+ if not digest:
+ return None
+ permanent_filename = f"asset_{digest}{extension}"
+
+ os.makedirs(LOCAL_ASSET_DIR, exist_ok=True)
+ destination_path = os.path.join(LOCAL_ASSET_DIR, permanent_filename)
+ if not os.path.exists(destination_path):
+ shutil.copyfile(source_path, destination_path)
+
+ return SavedAsset(
+ asset_id=asset_id,
+ public_url=_asset_url(asset_base_url, "local-assets", permanent_filename),
+ content_type=content_type,
+ )
diff --git a/backend/uploaded_assets/tools.py b/backend/uploaded_assets/tools.py
new file mode 100644
index 00000000..bdafc244
--- /dev/null
+++ b/backend/uploaded_assets/tools.py
@@ -0,0 +1,115 @@
+from typing import Any, Dict, List, cast
+
+from agent.state import ensure_str
+from agent.tools.types import CanonicalToolDefinition, ToolExecutionResult
+from uploaded_assets.store import promote_temporary_asset_id
+
+
+def _summarize_text(value: str, limit: int = 240) -> str:
+ if len(value) <= limit:
+ return value
+ return value[:limit] + "..."
+
+
+def _save_assets_schema() -> Dict[str, Any]:
+ return {
+ "type": "object",
+ "properties": {
+ "asset_ids": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "description": (
+ "Opaque temporary asset ID for an uploaded image that should be "
+ "promoted to a permanent asset URL."
+ ),
+ },
+ },
+ },
+ "required": ["asset_ids"],
+ }
+
+
+SAVE_ASSETS_TOOL_DEFINITION = CanonicalToolDefinition(
+ name="save_assets",
+ description=(
+ "Promote one or more uploaded temporary image asset IDs to permanent URLs. "
+ "Use this before embedding any uploaded images in code. "
+ "Returns permanent public_url values to use in the generated code."
+ ),
+ parameters=_save_assets_schema(),
+)
+
+
+def summarize_save_assets_input(args: Dict[str, Any]) -> Dict[str, Any]:
+ raw_asset_ids = args.get("asset_ids")
+ if isinstance(raw_asset_ids, list):
+ asset_ids = cast(List[Any], raw_asset_ids)
+ return {
+ "count": len(asset_ids),
+ "asset_ids": [ensure_str(asset_id) for asset_id in asset_ids],
+ }
+ return {"asset_ids": []}
+
+
+def run_save_assets(args: Dict[str, Any]) -> ToolExecutionResult:
+ raw_asset_ids = args.get("asset_ids")
+ if not isinstance(raw_asset_ids, list) or not raw_asset_ids:
+ return ToolExecutionResult(
+ ok=False,
+ result={"error": "save_assets requires a non-empty asset_ids list"},
+ summary={"error": "Missing asset_ids"},
+ )
+
+ asset_ids = cast(List[Any], raw_asset_ids)
+ cleaned = [
+ asset_id.strip() for asset_id in asset_ids if isinstance(asset_id, str)
+ ]
+ unique_asset_ids = list(
+ dict.fromkeys([asset_id for asset_id in cleaned if asset_id])
+ )
+ if not unique_asset_ids:
+ return ToolExecutionResult(
+ ok=False,
+ result={"error": "No valid asset IDs provided"},
+ summary={"error": "No valid asset_ids"},
+ )
+
+ results: List[Dict[str, Any]] = []
+ for asset_id in unique_asset_ids:
+ asset = promote_temporary_asset_id(asset_id)
+ if not asset:
+ results.append(
+ {
+ "asset_id": asset_id,
+ "public_url": None,
+ "content_type": None,
+ "status": "error",
+ }
+ )
+ continue
+
+ results.append(
+ {
+ "asset_id": asset_id,
+ "public_url": asset.public_url,
+ "content_type": asset.content_type,
+ "status": "ok",
+ }
+ )
+
+ summary_items: List[Dict[str, Any]] = []
+ for result in results:
+ summary_items.append(
+ {
+ "asset_id": _summarize_text(ensure_str(result["asset_id"]), 100),
+ "public_url": result["public_url"],
+ "content_type": result["content_type"],
+ "status": result["status"],
+ }
+ )
+ return ToolExecutionResult(
+ ok=True,
+ result={"images": results},
+ summary={"images": summary_items},
+ )
diff --git a/frontend/src/components/agent/AgentActivity.tsx b/frontend/src/components/agent/AgentActivity.tsx
index d01af32d..b5a61408 100644
--- a/frontend/src/components/agent/AgentActivity.tsx
+++ b/frontend/src/components/agent/AgentActivity.tsx
@@ -16,6 +16,7 @@ import {
BsImage,
BsScissors,
BsFiles,
+ BsBookmarkCheck,
} from "react-icons/bs";
import ReactMarkdown from "react-markdown";
import { Light as SyntaxHighlighterBase } from "react-syntax-highlighter";
@@ -107,6 +108,9 @@ function getEventIcon(type: AgentEventType, toolName?: string) {
if (toolName === "retrieve_option") {
return <BsFiles className="text-slate-500" />;
}
+ if (toolName === "save_assets") {
+ return <BsBookmarkCheck className="text-emerald-500" />;
+ }
return <BsFileEarmarkPlus className="text-gray-500" />;
}
@@ -149,6 +153,15 @@ function getEventTitle(event: AgentEvent): string {
? "Retrieving option"
: "Retrieved option";
}
+ if (event.toolName === "save_assets") {
+ const saveInput = event.input as any;
+ const saveOutput = event.output as any;
+ const saveCount = saveOutput?.images?.length || saveInput?.asset_ids?.length || 0;
+ if (event.status === "running") {
+ return saveCount > 1 ? `Saving ${saveCount} assets` : "Saving asset";
+ }
+ return saveCount > 1 ? `Saved ${saveCount} assets` : "Saved asset";
+ }
return event.status === "running" ? "Running tool" : "Tool completed";
}
return "Activity";
@@ -345,6 +358,58 @@ function renderToolDetails(event: AgentEvent, variantCode?: string) {
</div>
)}
+ {event.toolName === "save_assets" && !hasError && (
+ <div className="space-y-3">
+ {event.status === "running" && input?.asset_ids && Array.isArray(input.asset_ids) && (
+ <div className="divide-y divide-gray-100 dark:divide-gray-800">
+ {input.asset_ids.map((assetId: string, index: number) => (
+ <div key={`${assetId}-${index}`} className="py-2">
+ <div className="text-xs text-gray-500 dark:text-gray-400 mb-1">
+ Asset ID
+ </div>
+ <div className="break-all rounded bg-gray-50 p-2 font-mono text-xs text-gray-600 dark:bg-gray-800 dark:text-gray-300">
+ {assetId}
+ </div>
+ </div>
+ ))}
+ </div>
+ )}
+ {event.status !== "running" && output?.images && Array.isArray(output.images) && (
+ <div className="divide-y divide-gray-100 dark:divide-gray-800">
+ {output.images.map((item: any, index: number) => (
+ <div key={`${item.asset_id}-${index}`} className="flex gap-3 py-2">
+ <div className="w-1/2">
+ <div className="text-xs text-gray-500 dark:text-gray-400 mb-1">
+ Saved asset
+ </div>
+ {item.public_url ? (
+ <img
+ src={item.public_url}
+ alt={`Saved uploaded asset ${index + 1}`}
+ className="w-full rounded object-cover"
+ loading="lazy"
+ />
+ ) : (
+ <div className="aspect-square rounded bg-gray-100 dark:bg-gray-800 flex items-center justify-center text-xs text-gray-400">
+ Failed
+ </div>
+ )}
+ </div>
+ <div className="w-1/2 self-center">
+ <div className="text-xs text-gray-500 dark:text-gray-400">
+ Permanent URL
+ </div>
+ <div className="mt-1 break-all rounded bg-gray-50 p-2 font-mono text-xs text-gray-600 dark:bg-gray-800 dark:text-gray-300">
+ {item.public_url}
+ </div>
+ </div>
+ </div>
+ ))}
+ </div>
+ )}
+ </div>
+ )}
+
{!event.toolName && !hasError && (
<>
{event.input && (