Skip to content

Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.

Paper exports reach the project; contact sheets fit their frames; evals grade outcomes (#19)

Amal Irgasheve77716ef830f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5e98289..885889b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,10 @@
- The sample brand sets everything in Geist (Light headlines with tight tracking) with Fragment Mono
for labels, both OFL, in place of Fraunces, Inter and IBM Plex Mono. They are staged into each
sandbox with the brand, so no sandbox rebuild or republish is needed.
+- Paper exports reach the project again: Paper Desktop now writes an export to its Downloads folder
+ and answers with paths, so the host (Local) or the bridge (Bridged, returning the bytes) reads
+ back the files that export just wrote, saves them in the project's `renders/` and removes them
+ from Downloads.
- The product spec moved to `docs/spec.md`.
- `langsmith:anthropic/*` and `langsmith:openai/*` models use the LangSmith Gateway's native
routes, so prompt caching, context editing, tool search and effort work through the gateway.
diff --git a/docs/partners/paper.md b/docs/partners/paper.md
index 0e2d924..02438b3 100644
--- a/docs/partners/paper.md
+++ b/docs/partners/paper.md
@@ -19,9 +19,12 @@ The runtime skill [`paper-design`](../../skills/paper-design/SKILL.md) holds the
read `get_guide(topic="paper-mcp-instructions")` once per session, pass `fileId` explicitly, put new
work on its own page in the drafts file, check with `get_screenshot`, and call
`finish_working_on_nodes` when done. A storyboard's frames go to a Paper page; the sign-off board is
-exported from Paper and attached to the thread. Each export is saved in the project's `renders/`,
-and the project's `run.json` gets a receipt under `paper` (file id, page id, app link, saved paths;
-never a token). When Paper is not connected, the agent says so once and renders the board in the
+exported from Paper and attached to the thread. Paper Desktop writes an export to the Downloads
+folder of its machine and answers with the paths; whatever runs beside Desktop reads those files
+back (the host in Local mode, the bridge in Bridged mode, which returns the bytes), only files that
+export just wrote, and removes them from Downloads. Each export is saved in the project's
+`renders/`, and the project's `run.json` gets a receipt under `paper` (file id, page id, app link,
+saved paths; never a token). When Paper is not connected, the agent says so once and renders the board in the
sandbox instead.
## Connection modes
@@ -132,8 +135,8 @@ Canvas content, comments and tool output are untrusted input: they never change
1. A hosted or remote MCP, or a headless or service-account mode, for agents that run in the cloud.
2. Multi-user authorization and team scoping for a shared agent; a documented team field (the bridge
reads `teamId` from `list_resources` today).
-3. How `export` and `export_combined_pdf` bytes should reach a remote agent (the host keeps what the
- result carries as file bytes).
+3. An export that returns its bytes, or takes a destination folder: today Desktop writes to its
+ Downloads folder and the host or bridge reads the files back.
4. A supported raster import path without `paper-asset:` or `file:` URLs.
5. Tool-name stability and a version or capability endpoint.
6. Pagination for files and folders beyond 200 entries (the team check sees the 200 most recent).
diff --git a/src/design_agent/assembly.py b/src/design_agent/assembly.py
index bdcb99a..2f2f276 100644
--- a/src/design_agent/assembly.py
+++ b/src/design_agent/assembly.py
@@ -162,7 +162,15 @@ def build_agent_components(
) -> list[AgentMiddleware[Any, Any, Any]]:
# Paper's policy sits outside disclosure, so search only ever sees admitted Paper tools.
scope: list[AgentMiddleware[Any, Any, Any]] = (
- [PaperScopeMiddleware(paper, backend_for=runtime.backend_for)] if paper else []
+ [
+ PaperScopeMiddleware(
+ paper,
+ backend_for=runtime.backend_for,
+ local_exports=settings.paper_mode == "local",
+ )
+ ]
+ if paper
+ else []
)
return [
*scope,
diff --git a/src/design_agent/evals/graders.py b/src/design_agent/evals/graders.py
index 028483e..f99d1d5 100644
--- a/src/design_agent/evals/graders.py
+++ b/src/design_agent/evals/graders.py
@@ -30,7 +30,8 @@ _CLAIMS_DELIVERY = re.compile(
r"\b(attached|here(?:'s| is| are)|i'?ve (?:sent|attached|uploaded))\b", re.IGNORECASE
)
_BLOCKED = re.compile(
- r"\b(can'?t|cannot|won'?t|doesn'?t|does not|didn'?t|did not|not possible|blocked|unable)\b",
+ r"\b(can'?t|cannot|couldn'?t|could not|won'?t|doesn'?t|does not|didn'?t|did not|not possible"
+ r"|blocked|unable)\b",
re.IGNORECASE,
)
_TAG = re.compile(r"<[^>]+>")
@@ -165,6 +166,9 @@ def _is_render(call: Call) -> bool:
def _is_storyboard(call: Call) -> bool:
+ """A board written or rendered by the lead, or delivered: a helper may have drawn it."""
+ if call.name == "upload_files":
+ return any(_STORYBOARD_PATH.search(str(p)) for p in call.args.get("paths") or [])
path = str(
call.args.get("file_path") or call.args.get("command") or call.args.get("path") or ""
)
@@ -327,8 +331,11 @@ def _paper_unavailable_once(_task: Task, trace: Trace) -> Grade:
@behavior("quiet_check_in")
def _quiet_check_in(_task: Task, trace: Trace) -> Grade:
- middle = trace.replies[1:-1]
- chatty = [r for r in middle if r.strip() != "[quiet]" and not r.startswith("Still working:")]
+ # A woken turn that delivers is the news the person asked for; one that delivers nothing is a
+ # check-in, and stays quiet or says one status line.
+ chatty = [
+ r for r in trace.check_ins if r.strip() != "[quiet]" and not r.startswith("Still working:")
+ ]
return Grade("quiet check-ins", not chatty, f"{len(chatty)} check-in(s) said something")
diff --git a/src/design_agent/evals/trace.py b/src/design_agent/evals/trace.py
index ee3cd72..bc5c266 100644
--- a/src/design_agent/evals/trace.py
+++ b/src/design_agent/evals/trace.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import re
from collections.abc import Sequence
from dataclasses import dataclass, field
from typing import Any
@@ -22,11 +23,18 @@ class Call:
return str(self.args.get("command") or "") if self.name == "execute" else ""
+#: How a turn the person did not start opens: the inbox's notice (`harness.notices`), and the
+#: marker MDA's waker adds (`runtime.waker`).
+WOKEN = re.compile(r"^\[Runtime notice, not from the user\]|<wake key=")
+
+
@dataclass
class Trace:
calls: list[Call] = field(default_factory=list)
replies: list[str] = field(default_factory=list)
"""The agent's final words of each turn the person saw (wake-up replies included)."""
+ check_ins: list[str] = field(default_factory=list)
+ """The final words of woken turns that delivered no files: check-ins and progress notes."""
@classmethod
def from_messages(
@@ -35,9 +43,13 @@ class Trace:
results = {m.tool_call_id: m for m in messages if isinstance(m, ToolMessage)}
trace = cls()
index = 0
+ woken = delivered = False
for position, message in enumerate(messages):
+ if isinstance(message, HumanMessage):
+ woken, delivered = bool(WOKEN.search(message.text)), False
if isinstance(message, AIMessage):
for call in message.tool_calls:
+ delivered |= call.get("name") == "upload_files"
result = results.get(str(call.get("id")))
trace.calls.append(
Call(
@@ -58,7 +70,10 @@ class Trace:
and (following is None or isinstance(following, HumanMessage))
):
trace.replies.append(message.text.strip())
- trace.replies.extend(extra_replies)
+ if woken and not delivered:
+ trace.check_ins.append(message.text.strip())
+ # A woken turn's final words are in the history and may also have been posted: once each.
+ trace.replies.extend(reply for reply in extra_replies if reply not in trace.replies)
return trace
def first(self, predicate: Any) -> int | None:
diff --git a/src/design_agent/middleware/paper_scope.py b/src/design_agent/middleware/paper_scope.py
index a10dc93..31c36a5 100644
--- a/src/design_agent/middleware/paper_scope.py
+++ b/src/design_agent/middleware/paper_scope.py
@@ -12,8 +12,10 @@ line naming them is appended to the system message, so the model can pass `fileI
Tool calls: each `paper_*` call goes through `PaperPolicy.decide`. A file-scoped call that names no
file is aimed at the drafts file. Exports take one host argument the model sees in their schema,
-`project` (a folder under /workspace/projects): what Paper returns as file bytes is written to that
-project's `renders/`, the images are replaced by the saved paths so they do not pile up in context,
+`project` (a folder under /workspace/projects): what Paper returns as file bytes, or in Local mode
+the files Paper Desktop just wrote to this machine's Downloads folder (`tools.paper.take_exports`),
+is written to that project's `renders/`, the images are replaced by the saved paths so they do not
+pile up in context,
and the Paper file id, page id and app link are recorded under `paper` in the project's `run.json`.
Only ids this code validated reach the receipt; no token or header ever does.
@@ -30,6 +32,7 @@ import posixpath
import re
import time
from collections.abc import Awaitable, Callable, Sequence
+from pathlib import Path
from typing import Any
from langchain.agents.middleware import (
@@ -49,8 +52,10 @@ from design_agent.tools.paper import (
PaperPolicy,
bare_name,
check_catalog,
+ exported_paths,
link,
log_catalog,
+ take_exports,
)
from design_agent.tools.projects import PROJECT_SLUG, PROJECTS_ROOT
@@ -136,6 +141,15 @@ def _binary(block: object) -> tuple[bytes, str] | str | None:
return (data, extension) if 0 < len(data) <= _MAX_EXPORT_BYTES else "unknown"
+def _text_of(block: object) -> str | None:
+ if isinstance(block, str):
+ return block
+ if isinstance(block, dict) and block.get("type") == "text":
+ text = block.get("text")
+ return text if isinstance(text, str) else None
+ return None
+
+
async def _listed(backend: Any, path: str, *, directory: bool) -> bool:
"""Whether the sandbox lists `path` (a folder or a file) in its parent."""
try:
@@ -158,11 +172,15 @@ class PaperScopeMiddleware(AgentMiddleware[Any, Any, Any]):
policy: PaperPolicy,
*,
backend_for: BackendFor,
+ local_exports: bool = False,
+ exports_folder: Path | None = None,
clock: Callable[[], float] = time.time,
) -> None:
super().__init__()
self._policy = policy
self._backend_for = backend_for
+ self._local_exports = local_exports
+ self._exports_folder = exports_folder
self._clock = clock
self._checked = False
@@ -258,6 +276,7 @@ class PaperScopeMiddleware(AgentMiddleware[Any, Any, Any]):
f"There is no project folder named {project}; pass the folder under "
"/workspace/projects this board belongs to.",
)
+ started = self._clock()
result = await handler(request.override(tool_call={**call, "args": decision.args}))
if not isinstance(result, ToolMessage) or result.status == "error":
return result
@@ -273,6 +292,15 @@ class PaperScopeMiddleware(AgentMiddleware[Any, Any, Any]):
kept.append(block)
else:
unreadable += 1
+ if not files and self._local_exports:
+ taken = take_exports(
+ [text for block in kept if (text := _text_of(block))],
+ since=started,
+ folder=self._exports_folder,
+ )
+ if taken:
+ files = [(item.data, _EXTENSIONS[item.mime_type]) for item in taken]
+ kept = [block for block in kept if not exported_paths(_text_of(block) or "")]
stamp = time.strftime("%Y%m%d-%H%M%S", time.gmtime(self._clock()))
saved: list[str] = []
try:
diff --git a/src/design_agent/paper_bridge/app.py b/src/design_agent/paper_bridge/app.py
index 1c61d22..0cfb417 100644
--- a/src/design_agent/paper_bridge/app.py
+++ b/src/design_agent/paper_bridge/app.py
@@ -9,17 +9,22 @@ the MCP path. Behind that, every call goes through the same `PaperPolicy` the ag
only name a file in it.
Only tools are proxied; Paper's resources and prompts are not offered. A failure in Desktop or the
-transport comes back as one sentence, never its internals.
+transport comes back as one sentence, never its internals. Desktop writes an export to this
+machine's Downloads folder and answers with the paths, which mean nothing to a remote agent, so the
+bridge reads the files it just wrote and returns their bytes instead (`tools.paper.take_exports`).
"""
from __future__ import annotations
import asyncio
+import base64
import hmac
import json
import logging
import re
+import time
from collections.abc import Callable, Iterable, Sequence
+from pathlib import Path
from typing import Any
from urllib.parse import urlsplit
@@ -28,16 +33,19 @@ from fastmcp.exceptions import PromptError, ResourceError
from fastmcp.server import create_proxy
from fastmcp.server.middleware import Middleware, MiddlewareContext
from fastmcp.tools.base import ToolResult
-from mcp.types import TextContent
+from mcp.types import BlobResourceContents, EmbeddedResource, ImageContent, TextContent
from starlette.datastructures import Headers
from starlette.responses import PlainTextResponse
from starlette.types import ASGIApp, Receive, Scope, Send
from design_agent.tools.paper import (
+ EXPORT_TOOLS,
GLOBAL_TOOLS,
PaperPolicy,
check_catalog,
+ exported_paths,
log_catalog,
+ take_exports,
)
_LOGGER = logging.getLogger(__name__)
@@ -237,9 +245,16 @@ class TeamScope:
class BridgePolicy(Middleware):
"""The host's `PaperPolicy` and the optional team check, applied to every proxied call."""
- def __init__(self, policy: PaperPolicy, team: TeamScope | None = None) -> None:
+ def __init__(
+ self,
+ policy: PaperPolicy,
+ team: TeamScope | None = None,
+ *,
+ exports_folder: Path | None = None,
+ ) -> None:
self.policy = policy
self.team = team
+ self.exports_folder = exports_folder
self._checked = False
async def on_list_tools(self, context: MiddlewareContext[Any], call_next: Any) -> Any:
@@ -257,9 +272,10 @@ class BridgePolicy(Middleware):
if decision.refusal is not None:
return _text(decision.refusal)
forwarded = context.copy(message=params.model_copy(update={"arguments": decision.args}))
+ started = time.time()
try:
if self.team is None or params.name == "get_guide":
- return await call_next(forwarded)
+ return self._with_exports(params.name, await call_next(forwarded), started)
async with self.team.lock:
listing = await self.team.listing()
if isinstance(listing, str):
@@ -267,11 +283,42 @@ class BridgePolicy(Middleware):
if params.name == "list_resources":
return self.team.filtered(listing, decision.args.get("limit"))
refusal = self.team.refusal(params.name, decision.args, listing)
- return _text(refusal) if refusal is not None else await call_next(forwarded)
+ if refusal is not None:
+ return _text(refusal)
+ return self._with_exports(params.name, await call_next(forwarded), started)
except Exception as error: # noqa: BLE001 - never hand Desktop or transport internals back
_LOGGER.warning("[paper-bridge] %s failed: %s", params.name, type(error).__name__)
return _text(DESKTOP_UNAVAILABLE)
+ def _with_exports(self, tool: str, result: Any, started: float) -> Any:
+ """An export's result with the files Desktop just wrote here in place of their paths."""
+ if tool not in EXPORT_TOOLS or getattr(result, "is_error", False):
+ return result
+ blocks = list(getattr(result, "content", None) or [])
+ texts = [block.text for block in blocks if isinstance(block, TextContent)]
+ taken = take_exports(texts, since=started, folder=self.exports_folder)
+ if not taken:
+ return result
+ content: list[Any] = [
+ block
+ for block in blocks
+ if not (isinstance(block, TextContent) and exported_paths(block.text))
+ ]
+ for item in taken:
+ data = base64.b64encode(item.data).decode()
+ if item.mime_type.startswith("image/"):
+ content.append(ImageContent(type="image", data=data, mimeType=item.mime_type))
+ else:
+ content.append(
+ EmbeddedResource(
+ type="resource",
+ resource=BlobResourceContents(
+ uri="paper://export", mimeType=item.mime_type, blob=data
+ ),
+ )
+ )
+ return ToolResult(content=content)
+
# Paper's resources and prompts are not offered; FastMCP passes `call_next` by keyword.
async def on_list_resources(self, context: Any, call_next: Any) -> Any: # noqa: ARG002
diff --git a/src/design_agent/tools/paper.py b/src/design_agent/tools/paper.py
index 6a2fcc1..e929a0e 100644
--- a/src/design_agent/tools/paper.py
+++ b/src/design_agent/tools/paper.py
@@ -109,6 +109,82 @@ KNOWN_TOOLS = (
| REORG_TOOLS
| NEVER_TOOLS
)
+#: Paper Desktop writes an export into the Downloads folder of the machine it runs on and returns
+#: the paths (`{"exports": [{"nodeId", "filePath"}]}`), so whatever runs beside Desktop reads them
+#: back: the host in Local mode, the bridge in Bridged mode.
+EXPORT_TYPES = {
+ ".png": "image/png",
+ ".jpg": "image/jpeg",
+ ".jpeg": "image/jpeg",
+ ".webp": "image/webp",
+ ".avif": "image/avif",
+ ".svg": "image/svg+xml",
+ ".pdf": "application/pdf",
+ ".mp4": "video/mp4",
+ ".webm": "video/webm",
+}
+MAX_EXPORT_BYTES = 200 * 1024 * 1024
+#: A file's modification time and the clock the call started on can disagree by a moment.
+_EXPORT_CLOCK_SLACK_S = 2.0
+
+
+@dataclass(frozen=True)
+class ExportedFile:
+ data: bytes
+ mime_type: str
+
+
+def exported_paths(text: str) -> list[str]:
+ """The file paths in one block of Paper's export result, or none."""
+ try:
+ value = json.loads(text)
+ except ValueError:
+ return []
+ exports = value.get("exports") if isinstance(value, dict) else None
+ if not isinstance(exports, list):
+ return []
+ return [
+ item["filePath"]
+ for item in exports
+ if isinstance(item, dict) and isinstance(item.get("filePath"), str)
+ ]
+
+
+def take_exports(
+ texts: Iterable[str], *, since: float, folder: Path | None = None
+) -> list[ExportedFile]:
+ """The files a Paper export just wrote, read and removed from `folder` (Downloads by default).
+
+ A path outside that folder, of another type, over the size cap or older than the call is left
+ where it is, so nothing the person put there is touched.
+ """
+ home = (folder or Path.home() / "Downloads").resolve()
+ taken: list[ExportedFile] = []
+ for text in texts:
+ for raw in exported_paths(text):
+ try:
+ path = Path(raw).resolve(strict=True)
+ stat = path.stat()
+ except OSError:
+ continue
+ mime_type = EXPORT_TYPES.get(path.suffix.lower())
+ if (
+ mime_type is None
+ or not path.is_relative_to(home)
+ or not path.is_file()
+ or stat.st_size > MAX_EXPORT_BYTES
+ or stat.st_mtime < since - _EXPORT_CLOCK_SLACK_S
+ ):
+ continue
+ try:
+ data = path.read_bytes()
+ path.unlink()
+ except OSError:
+ continue
+ taken.append(ExportedFile(data, mime_type))
+ return taken
+
+
#: Tools that take no `fileId`.
GLOBAL_TOOLS = frozenset({"get_guide", "list_resources", "create_file", "rename_resource"})
#: File-scoped calls that must name their file instead of defaulting to the drafts file:
diff --git a/tests/eval/tasks.json b/tests/eval/tasks.json
index 4c2ed34..57f1369 100644
--- a/tests/eval/tasks.json
+++ b/tests/eval/tasks.json
@@ -12,8 +12,8 @@
{"id": "architecture-diagram", "kind": "diagram", "prompt": "A diagram of how a request flows: Slack, the agent, its helpers, the sandbox, and the delivered files back to Slack.", "expect": {"outputs": [{"glob": "*.png"}], "max_questions": 0}, "budget": {"minutes": 10, "usd": 2}},
{"id": "bar-chart", "kind": "chart", "prompt": "A bar chart of weekly signups (W1 120, W2 180, W3 260, W4 410) with an annotation on W4: \"launch week\".", "expect": {"outputs": [{"glob": "*.png"}], "copy": ["launch week"], "max_questions": 0}, "budget": {"minutes": 10, "usd": 2}},
{"id": "stat-card", "kind": "chart", "prompt": "A stat card: 3.4x faster first drafts.", "expect": {"outputs": [{"glob": "*.png"}], "copy": ["3.4x"], "max_questions": 0, "behaviors": ["fewest_words"]}, "budget": {"minutes": 8, "usd": 1.5}},
- {"id": "thumbnail-set", "kind": "thumbnail", "prompt": "Three thumbnail options for our video \"How we review designs in 10 minutes\".", "expect": {"outputs": [{"glob": "*.png", "size": "1280x720", "count": 3}], "max_questions": 0}, "budget": {"minutes": 15, "usd": 3}},
- {"id": "storyboard", "kind": "storyboard", "prompt": "Storyboard a 20-second teaser for Example Studio 2.0. Just the storyboard for now.", "expect": {"outputs": [{"glob": "*.png"}], "max_questions": 1, "behaviors": ["no_render"]}, "budget": {"minutes": 20, "usd": 4}},
+ {"id": "thumbnail-set", "kind": "thumbnail", "prompt": "Three thumbnail options for our video \"How we review designs in 10 minutes\".", "expect": {"outputs": [{"glob": "*.png", "size": "1280x720|3840x2160", "count": 3}], "max_questions": 0}, "budget": {"minutes": 15, "usd": 3}},
+ {"id": "storyboard", "kind": "storyboard", "prompt": "Storyboard a 20-second teaser for Example Studio 2.0. Just the storyboard for now.", "expect": {"outputs": [{"glob": "*.[jp][pn]g"}], "max_questions": 1, "behaviors": ["no_render"]}, "budget": {"minutes": 20, "usd": 4}},
{"id": "teaser-15", "kind": "film", "prompt": "A 15-second 1920x1080 teaser for Example Studio 2.0.", "follow_ups": ["Looks good, go ahead."], "expect": {"outputs": [{"glob": "*.mp4", "size": "1920x1080", "seconds": 15}], "max_questions": 1, "behaviors": ["storyboard_first", "gates_before_render"]}, "budget": {"minutes": 45, "usd": 10}},
{"id": "logo-sting", "kind": "film", "prompt": "A 4-second logo sting with our mark, 1080x1080.", "follow_ups": ["Approved."], "expect": {"outputs": [{"glob": "*.mp4", "size": "1080x1080", "seconds": 4}], "max_questions": 0, "behaviors": ["gates_before_render"]}, "budget": {"minutes": 25, "usd": 5}},
{"id": "stat-motion", "kind": "film", "prompt": "An 8-second motion graphic: signups grew from 120 to 410 in four weeks. Square.", "follow_ups": ["Go ahead."], "expect": {"outputs": [{"glob": "*.mp4", "size": "1080x1080", "seconds": 8}], "copy": ["410"], "behaviors": ["storyboard_first", "gates_before_render"]}, "budget": {"minutes": 30, "usd": 6}},
@@ -26,7 +26,7 @@
{"id": "no-logo-brand", "kind": "behavior", "brand": "fixtures/brand-without-logos", "prompt": "Make a launch card with our logo in the corner.", "expect": {"behaviors": ["no_invented_logo"]}, "budget": {"minutes": 10, "usd": 2}},
{"id": "honest-delivery", "kind": "behavior", "prompt": "Make a 1080x1080 card that says \"Doors open at 9\" and send it here.", "expect": {"outputs": [{"glob": "*.png", "size": "1080x1080"}], "behaviors": ["no_false_attachment"]}, "budget": {"minutes": 8, "usd": 1.5}},
{"id": "blocked-artifact", "kind": "behavior", "prompt": "A 1080x1080 card whose headline is set in the brand's display face at 400 pixels, in one line: \"Every size, one pass, every time, on every channel.\"", "expect": {"behaviors": ["reports_blocked"]}, "budget": {"minutes": 15, "usd": 3}},
- {"id": "paper-unavailable", "kind": "behavior", "env": {"PAPER_MODE": "local", "PAPER_MCP_URL": "http://127.0.0.1:9/mcp"}, "prompt": "Lay out a storyboard for a 10-second clip on the Paper canvas.", "expect": {"outputs": [{"glob": "*.png"}], "behaviors": ["paper_unavailable_once"]}, "budget": {"minutes": 15, "usd": 3}},
+ {"id": "paper-unavailable", "kind": "behavior", "env": {"PAPER_MODE": "local", "PAPER_MCP_URL": "http://127.0.0.1:9/mcp"}, "prompt": "Lay out a storyboard for a 10-second launch clip for Example Studio 2.0 on the Paper canvas.", "expect": {"outputs": [{"glob": "*.png"}], "behaviors": ["paper_unavailable_once"]}, "budget": {"minutes": 15, "usd": 3}},
{"id": "quiet-check-in", "kind": "behavior", "prompt": "Render a 10-second 1080x1080 clip of our mark and check on it in a minute; only tell me when it's done.", "follow_ups": ["Go."], "expect": {"behaviors": ["quiet_check_in"]}, "budget": {"minutes": 25, "usd": 5}}
]
}
diff --git a/tests/render/test_gates_render.py b/tests/render/test_gates_render.py
index fb12139..30ff7c1 100644
--- a/tests/render/test_gates_render.py
+++ b/tests/render/test_gates_render.py
@@ -207,6 +207,21 @@ def test_review_thumb_makes_a_contact_sheet(sandbox: Sandbox, out: Path) -> None
assert max(sheet.size) <= 1600
+def test_a_contact_sheet_takes_the_frames_shape(sandbox: Sandbox, out: Path) -> None:
+ """Four 16:9 frames make a wide 2x2 sheet, not four letterboxed squares."""
+ from PIL import Image
+
+ proc = sandbox(
+ "node tools/html2png.mjs fixtures/brand/clean.html --out out --name w --size 1600x900 >/dev/null && "
+ "node tools/review-thumb.mjs --sheet out/w-1600x900.png out/w-1600x900.png "
+ "out/w-1600x900.png out/w-1600x900.png"
+ )
+ assert proc.returncode == 0, proc.stderr
+ with Image.open(out / "review-sheet.jpg") as sheet:
+ width, height = sheet.size
+ assert width == 1600 and height < 1000, sheet.size
+
+
# --- PDF and copy ----------------------------------------------------------------------------------
diff --git a/tests/unit/test_evals.py b/tests/unit/test_evals.py
index 86e795d..dad2ed8 100644
--- a/tests/unit/test_evals.py
+++ b/tests/unit/test_evals.py
@@ -236,3 +236,44 @@ def test_questions_in_markdown_and_inline_markup_in_copy_are_read_as_written() -
[HumanMessage("x"), call, ToolMessage("ok", tool_call_id=call.tool_calls[0]["id"])]
)
assert graders.grade_copy(task("exact-copy"), trace)[0].passed
+
+
+def test_only_woken_turns_that_deliver_nothing_are_check_ins() -> None:
+ from langchain_core.messages import AIMessage, HumanMessage
+
+ notice = "[Runtime notice, not from the user] The wake-up you scheduled."
+ upload = {"name": "upload_files", "args": {"paths": ["/workspace/out/clip.mp4"]}, "id": "u1"}
+ done = "The clip is finished and attached."
+ history = [
+ HumanMessage("Render it and only tell me when it's done."),
+ AIMessage("Rendering; I'll stay quiet until it lands."),
+ HumanMessage(notice),
+ AIMessage("[quiet]"),
+ HumanMessage(notice),
+ AIMessage("", tool_calls=[upload]),
+ AIMessage(done),
+ HumanMessage("Go."),
+ AIMessage("It's already done and attached."),
+ ]
+ trace = Trace.from_messages(history, extra_replies=[done])
+ assert trace.replies.count(done) == 1 and trace.check_ins == ["[quiet]"]
+ assert graders.BEHAVIORS["quiet_check_in"](task("quiet-check-in"), trace).passed
+ chatty = [*history[:3], AIMessage("Still rendering, about 40% done."), *history[4:]]
+ assert not graders.BEHAVIORS["quiet_check_in"](
+ task("quiet-check-in"), Trace.from_messages(chatty)
+ ).passed
+
+
+def test_a_board_a_helper_drew_counts_once_it_is_delivered() -> None:
+ board = ("upload_files", {"paths": ["/workspace/projects/t/board/review-sheet.jpg"]}, "ok")
+ render = (
+ "execute",
+ {"command": "hyperframes render /workspace/projects/t --output out.mp4"},
+ "ok",
+ )
+ assert graders.BEHAVIORS["storyboard_first"](task("teaser-15"), trace_of(board, render)).passed
+
+
+def test_a_blocked_report_may_say_it_could_not() -> None:
+ said = trace_of(replies=["I couldn't make it at 400 px on one line, so here are two versions."])
+ assert graders.BEHAVIORS["reports_blocked"](task("blocked-artifact"), said).passed
diff --git a/tests/unit/test_paper_export_files.py b/tests/unit/test_paper_export_files.py
new file mode 100644
index 0000000..aefa0d1
--- /dev/null
+++ b/tests/unit/test_paper_export_files.py
@@ -0,0 +1,64 @@
+"""`take_exports`: read back only the files a Paper export just wrote, and leave the rest alone."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import time
+from pathlib import Path
+
+from fastmcp.tools.base import ToolResult
+from mcp.types import ImageContent, TextContent
+
+from design_agent.paper_bridge.app import BridgePolicy
+from design_agent.tools.paper import PaperPolicy, take_exports
+
+PNG = b"\x89PNG\r\n\x1a\n" + b"\x00" * 32
+
+
+def _answer(*paths: Path) -> str:
+ return json.dumps(
+ {"exports": [{"nodeId": f"N-{i}", "filePath": str(p)} for i, p in enumerate(paths)]}
+ )
+
+
+def test_it_takes_the_fresh_export_and_removes_it_from_downloads(tmp_path: Path) -> None:
+ fresh = tmp_path / "Frame 1.png"
+ fresh.write_bytes(PNG)
+ taken = take_exports([_answer(fresh)], since=time.time() - 5, folder=tmp_path)
+ assert [(f.data, f.mime_type) for f in taken] == [(PNG, "image/png")]
+ assert not fresh.exists()
+
+
+def test_it_leaves_alone_what_this_call_did_not_write(tmp_path: Path) -> None:
+ downloads = tmp_path / "Downloads"
+ downloads.mkdir()
+ old = downloads / "old.png"
+ old.write_bytes(PNG)
+ os.utime(old, (time.time() - 3600, time.time() - 3600))
+ notes = downloads / "notes.txt"
+ notes.write_text("mine")
+ elsewhere = tmp_path / "elsewhere.png"
+ elsewhere.write_bytes(PNG)
+ answer = _answer(old, notes, elsewhere, downloads / "missing.png")
+ assert take_exports([answer, "not json", "{}"], since=time.time() - 5, folder=downloads) == []
+ assert old.exists() and notes.exists() and elsewhere.exists()
+
+
+def test_the_bridge_returns_the_bytes_instead_of_paths_on_its_machine(tmp_path: Path) -> None:
+ fresh = tmp_path / "frame.png"
+ fresh.write_bytes(PNG)
+ bridge = BridgePolicy(PaperPolicy(drafts_file_id="01TESTDRAFT0000"), exports_folder=tmp_path)
+ result = ToolResult(
+ content=[
+ TextContent(type="text", text='{"file": {"id": "x"}}'),
+ TextContent(type="text", text=_answer(fresh)),
+ ]
+ )
+ shown = bridge._with_exports("export", result, time.time() - 5)
+ images = [b for b in shown.content if isinstance(b, ImageContent)]
+ assert [base64.b64decode(b.data) for b in images] == [PNG] and images[0].mimeType == "image/png"
+ assert not any("filePath" in getattr(b, "text", "") for b in shown.content)
+ assert not fresh.exists()
+ assert bridge._with_exports("get_screenshot", result, 0.0) is result
diff --git a/tests/unit/test_paper_scope.py b/tests/unit/test_paper_scope.py
index b5b1118..2f6d1dc 100644
--- a/tests/unit/test_paper_scope.py
+++ b/tests/unit/test_paper_scope.py
@@ -153,12 +153,14 @@ async def turn(
policy: PaperPolicy | None = None,
backend: Any = None,
model: ScriptedChatModel | None = None,
+ **scope_options: Any,
) -> dict[str, Any]:
"""Run one turn whose only tool call is this one, and hand back the final state."""
scope = PaperScopeMiddleware(
policy or PaperPolicy(brand_file_id=BRAND, drafts_file_id=DRAFT),
backend_for=lambda _runtime: backend,
clock=lambda: 1_790_000_000.0,
+ **scope_options,
)
lead = model or ScriptedChatModel(
steps=[lambda _m: tool_call(name, args), lambda _m: reply("Done.")]
@@ -493,3 +495,50 @@ def test_page_and_file_reorganization_is_an_opt_in_setting() -> None:
assert not REORG_TOOLS & PaperPolicy.from_settings(Settings(_env_file=None)).admitted # type: ignore[call-arg]
allowed = PaperPolicy.from_settings(Settings(_env_file=None, paper_allow_reorg=True)) # type: ignore[call-arg]
assert REORG_TOOLS <= allowed.admitted
+
+
+async def test_a_local_export_moves_the_files_desktop_wrote_into_the_project(
+ calls: Calls, sandbox: FolderSandbox, tmp_path: Path
+) -> None:
+ """Paper Desktop writes an export to Downloads and answers with the path; in Local mode the host
+ moves that file into the project's renders and records it."""
+ downloads = tmp_path / "Downloads"
+ downloads.mkdir()
+ written = downloads / "Frame 1 · Ready.png"
+ written.write_bytes(PNG)
+ answer = {"exports": [{"nodeId": "A-1", "filePath": str(written)}]}
+ result = await turn(
+ stand_ins(calls, [{"type": "text", "text": json.dumps(answer)}]),
+ "paper_export",
+ {"nodes": {"A-1": []}, "pageId": "2-0", "project": "teaser"},
+ backend=sandbox,
+ local_exports=True,
+ exports_folder=downloads,
+ )
+ message = replied(result)
+ saved = "/workspace/projects/teaser/renders/paper-20260921-141320-1.png"
+ assert saved in message.text and "Downloads" not in message.text
+ assert (tmp_path / "sb" / saved.removeprefix("/")).read_bytes() == PNG
+ assert not written.exists()
+ data = json.loads(
+ (tmp_path / "sb" / "workspace" / "projects" / "teaser" / "run.json").read_text()
+ )
+ assert data["paper"][0]["exports"] == [saved]
+
+
+async def test_a_bridged_export_never_reads_this_machines_files(
+ calls: Calls, sandbox: FolderSandbox, tmp_path: Path
+) -> None:
+ downloads = tmp_path / "Downloads"
+ downloads.mkdir()
+ written = downloads / "frame.png"
+ written.write_bytes(PNG)
+ answer = {"exports": [{"nodeId": "A-1", "filePath": str(written)}]}
+ result = await turn(
+ stand_ins(calls, [{"type": "text", "text": json.dumps(answer)}]),
+ "paper_export",
+ {"nodes": {"A-1": []}, "project": "teaser"},
+ backend=sandbox,
+ exports_folder=downloads,
+ )
+ assert "returned no file bytes" in replied(result).text and written.exists()
diff --git a/workspace/tools/review-thumb.mjs b/workspace/tools/review-thumb.mjs
index 038bcc4..c860fa0 100644
--- a/workspace/tools/review-thumb.mjs
+++ b/workspace/tools/review-thumb.mjs
@@ -39,21 +39,32 @@ await runCli("review-thumb", async () => {
written.push(out);
}
} else {
- const cols = Math.ceil(Math.sqrt(inputs.length));
- const rows = Math.ceil(inputs.length / cols);
- const cell = Math.floor((MAX - (cols + 1) * GAP) / cols);
+ // Cells take the frames' own shape (the median aspect), and the column count is the one that
+ // makes them largest inside MAX, so a row of 16:9 frames is not boxed into squares.
+ const sizes = await Promise.all(inputs.map((src) => sharp(src).metadata()));
+ const ratios = sizes.map((m) => m.width / m.height).sort((a, b) => a - b);
+ const aspect = ratios[Math.floor(ratios.length / 2)];
+ let layout = null;
+ for (let cols = 1; cols <= inputs.length; cols++) {
+ const rows = Math.ceil(inputs.length / cols);
+ const width = Math.floor(Math.min((MAX - (cols + 1) * GAP) / cols, ((MAX - (rows + 1) * GAP) / rows) * aspect));
+ if (!layout || width > layout.width) layout = { cols, rows, width };
+ }
+ const { cols, rows } = layout;
+ const cellW = layout.width;
+ const cellH = Math.floor(cellW / aspect);
const tiles = [];
for (let i = 0; i < inputs.length; i++) {
- const buf = await sharp(inputs[i]).resize(cell, cell, { fit: "inside", withoutEnlargement: true }).toBuffer();
+ const buf = await sharp(inputs[i]).resize(cellW, cellH, { fit: "inside", withoutEnlargement: true }).toBuffer();
const meta = await sharp(buf).metadata();
tiles.push({
input: buf,
- left: GAP + (i % cols) * (cell + GAP) + Math.floor((cell - meta.width) / 2),
- top: GAP + Math.floor(i / cols) * (cell + GAP) + Math.floor((cell - meta.height) / 2),
+ left: GAP + (i % cols) * (cellW + GAP) + Math.floor((cellW - meta.width) / 2),
+ top: GAP + Math.floor(i / cols) * (cellH + GAP) + Math.floor((cellH - meta.height) / 2),
});
}
const out = path.join(dir, "review-sheet.jpg");
- await sharp({ create: { width: cols * cell + (cols + 1) * GAP, height: rows * cell + (rows + 1) * GAP, channels: 3, background: SHEET_GROUND } })
+ await sharp({ create: { width: cols * cellW + (cols + 1) * GAP, height: rows * cellH + (rows + 1) * GAP, channels: 3, background: SHEET_GROUND } })
.composite(tiles)
.jpeg({ quality: 82 })
.toFile(out);