Add safe Remote UI preview support for generated HTML artifacts

[zainfathoni]

This was generated by AI during triage.

Motivation

Some agent/skill workflows generate HTML files as explanations, reports, or learning artifacts. For example, teaching/explanation skills may produce standalone HTML pages that are much more useful when viewed in a browser than as plain text.

Some of those files are static reference documents. Others may be interactive lessons with local JavaScript for audio buttons, quizzes, or immediate feedback. Tycho should expose these artifacts in a way that is useful while still treating generated HTML as untrusted content.

Proposed approach

Introduce a conventional per-agent artifact directory:

~/.tycho/logs/agents/{agent_id}/artifacts/

Tycho would discover files from that directory and expose them through the Remote API/UI.

Suggested behavior:

• Agents/skills can write generated assets into their own artifacts/ directory.
• GET /api/agents/:id/artifacts lists artifact files for that agent.
• GET /artifacts/:id/:artifact_path serves a specific artifact file.
• The Remote UI shows an “Artifacts” section on the agent detail page.
• HTML files can be previewed in a sandboxed iframe.
• Other common text/image assets can be previewed where safe.
• Unknown or binary files are download-only.

HTML security model

Generated HTML should be treated as untrusted content.

The default HTML preview should be static/safe:

<iframe sandbox src="/artifacts/:agent_id/:artifact_path"></iframe>

This supports reference docs, reports, and static explanations without giving generated content access to Tycho’s Remote UI or agent-control API.

For artifacts that intentionally rely on local JavaScript, Tycho could provide an explicit trusted interactive preview mode:

<iframe sandbox="allow-scripts" src="/artifacts/:agent_id/:artifact_path"></iframe>

This should still avoid allow-same-origin, so generated scripts run in a sandboxed opaque origin rather than Tycho’s app origin.

Artifact responses should also use conservative headers, for example:

X-Content-Type-Options: nosniff
Content-Security-Policy: default-src 'none'; img-src 'self' data: blob:; style-src 'unsafe-inline'; font-src 'self' data:;

Initial constraints:

• No arbitrary filesystem paths.
• Only serve files under the known per-agent artifact directory.
• Reject path traversal.
• Reject symlinks that escape the artifact root.
• Do not allow JavaScript in the default preview.
• Require an explicit user action/configuration for interactive JavaScript previews, if supported.
• Provide download/open actions separately from inline preview.

Artifact declaration

For the first version, Tycho can discover files directly from the conventional artifacts/ directory.

A later version could optionally support richer metadata through structured agent results or an artifacts.json file, for example custom titles, descriptions, or preferred preview type.

Retention/archive behavior

Artifacts should live under the existing per-agent log directory and be retained/archived with the agent’s other runtime files.

Non-goals for the first implementation

• Serving arbitrary project-relative paths.
• Allowing generated HTML to run JavaScript by default.
• Granting generated HTML same-origin access to Tycho’s Remote UI.
• Supporting a separate artifact origin or port.
• Requiring structured result schema changes before artifacts can be shown.

Rationale

A conventional per-agent artifact directory keeps the first implementation simple and safe. Static sandboxed previews cover reports and reference docs, while an explicit allow-scripts mode leaves room for interactive lesson artifacts without giving them same-origin access to Tycho itself.

[firewalker06]

The feature is valuable, but the security risk is the main design constraint. Generated HTML must be treated as untrusted content: if it is served too broadly, allowed to escape its artifact root, or previewed with overly permissive iframe flags, it could reach Tycho's Remote UI origin, agent-control API, bearer-auth context, or local files exposed by mistake.

Recommendation: make the first milestone deliberately tight:

• only discover files under the owning agent's known artifact/attachment root
• reject path traversal and symlink escapes using canonical path containment checks
• serve with X-Content-Type-Options: nosniff
• use a restrictive CSP for artifact responses
• preview HTML only in a default sandboxed iframe, e.g. <iframe sandbox src="..."></iframe>
• keep JavaScript disabled in the default preview
• make unknown/binary content download-only

I would defer interactive HTML previews (sandbox="allow-scripts") to a later milestone behind an explicit user action or trust setting, and still avoid allow-same-origin. The first version should prove safe static preview and download behavior before adding any executable artifact mode.