Artifacts and Media
OpenSquilla can create and deliver files as part of agent work: reports, HTML files, PDFs, slide decks, spreadsheets, generated images, and other artifacts. Use artifacts when the output is too large, visual, structured, or important to leave only in chat text.
Artifacts
Artifacts are user-visible files created during a session. In Web UI chat they appear as artifact cards when the runtime publishes them. In CLI runs, artifact events can include file names, ids, and download URLs.
Common use cases:
- generate a report;
- create a standalone HTML prototype;
- build a CSV/XLSX workbook;
- create a PDF briefing;
- produce a slide deck;
- package generated output for channel delivery.
Ask directly:
Create a one-page HTML dashboard from this data and publish it as an artifact.
Generate a PDF briefing with sources and publish the final file.
The Agent creates CSV, XLSX, PPTX, and PDF files with ordinary workspace tools,
execute_code, and document skills, then calls publish_artifact. Generation
and publication use the same path regardless of the requested file format.
In ordinary channel sessions, generation requires a Gateway-attested managed workspace and sandbox; unavailable isolation does not enable host execution. See ordinary channel sessions.
Channel delivery verifies the artifact against the admitted session and pins
it to the original inbound account, conversation, and thread. The outbox assigns
a stable delivery identity. Replaying a completed send reuses its receipt;
an uncertain provider response is retained as unknown rather than blindly
uploading and sending again. Cross-session artifacts are rejected, including
their fallback download links. Platform file limits still apply.
HTML projects and webpage preview
publish_artifact can preserve a generated HTML project instead of publishing
only its entry file:
publish_artifact(
path="site/index.html",
bundle="directory",
bundle_root="site",
)
bundle="auto"(the default) follows statically identifiable local references from HTML, CSS, and JavaScript. Publication rejects missing or unsafe statically identifiable local dependencies.bundle="directory"snapshots the complete dedicated project directory and fails atomically if it contains a rejected path or sensitive file.bundle="none"preserves the legacy single-file behavior.
Remote URLs and dynamic references are preserved; they are not converted into an offline dependency bundle. A newly published single-file HTML must not depend on identifiable local files missing from its stored content.
Historical single-file HTML remains readable without migration. If it refers to local CSS, scripts, or other files that were never stored, the preview is reported as partial instead of silently claiming that every resource loaded.
Generated web projects should use a dedicated subdirectory and directory
mode. Bundles are static sites: OpenSquilla does not start Vite, webpack, HMR,
or a project backend for them. Open an already-running development server in
the Desktop side browser when the project needs those services.
Desktop and a loopback Web UI default to a full-network preview. This runs the page in a temporary, isolated browser context: normal browser JavaScript, modules, workers, WebAssembly, WebGL, fonts, media, HTTP(S), WebSocket, and page-level CORS/CSP rules still apply, but the page receives no OpenSquilla credentials, Node/Electron APIs, host files, or system-browser login state. Desktop offline mode keeps JavaScript enabled while restricting network access to the artifact itself, including blocking WebRTC/TURN/STUN and speculative DNS. A browser-hosted offline preview cannot enforce that all-protocol boundary against arbitrary page JavaScript. It therefore runs bundle scripts in an opaque sandbox with a restrictive response policy; external network access is blocked, while workers, service workers, persistent storage, and root-absolute paths are not guaranteed. A Web UI reached from another machine is always forced to this visibly limited offline preview.
Set OPENSQUILLA_PREVIEW_FORCE_OFFLINE=1 before starting the Desktop app or
gateway to disable full-network artifact previews as an incident-response
measure.
Use Annotate on an open page to attach selections and instructions to an ordinary chat message. The Agent chooses whether to inspect files, edit them, or use the Desktop browser tool on the existing preview. An annotation does not prescribe a sequence of tools. See the HTML annotation and editing guide for working-file behavior, browser availability, and upgrade compatibility.
Workbench resources and editable Documents
The resource Workbench presents several related kinds of content in the same right-hand panel:
- an attachment is an immutable session input;
- a Document has normal working files, a current version, immutable historical Revisions, and audited changes;
- a deliverable is an immutable published snapshot;
- a preview is temporary host state that displays those resources.
A historical deliverable card opens and downloads its published version. If version A was published and the working files later changed to B, the old card still shows A. Choose Continue editing to open the current working version B. External-open actions also keep the selected historical version and open its materialized copy on the execution host.
Opening supported HTML for editing imports a copy into a Document. Repeated or response-lost imports resolve the same durable receipt, and editing the copy never changes the source attachment. A generated HTML project that has been published can retain its exact workspace source as the Document’s working files, so later edits continue the same document.
Working files include the HTML entry and its saved local resources. Preview reflects those files; a successfully completed turn saves a version when the bundle changed. Failed or cancelled turns retain working files for later work without automatically saving a completion version. An explicit publication that already succeeded remains in history. Restoring a version restores its owned resource bundle while preserving unrelated workspace files. Publishing fixes a selected Revision into a deliverable that later edits cannot change.
The editable entry must be supported, NUL-free UTF-8 HTML within the format’s size limits; saved CSS, JavaScript, images, and other local bundle resources stay with it. This does not make Office formats editable: they remain available for discovery and download, with preview and edit support reported per format. Remote URLs and arbitrary workspace paths are not accepted as attachment imports. Generated workspace sources are bound only through their verified publication provenance; automatic upload promotion is not used.
When to Use Artifacts Instead of Chat
Use artifacts for:
- files the user should download or share;
- tables or reports that need layout;
- generated apps, dashboards, or prototypes;
- long output that would be awkward in chat;
- channel delivery where the platform supports file upload.
Use chat text for short answers, decisions, and next steps.
Document Skills
OpenSquilla includes skills for common document formats:
docxfor Word documents;pptxfor PowerPoint decks;xlsxfor Excel workbooks;pdf-toolkitfor structured PDF work;html-to-pdffor styled PDF rendering.
Discover them:
opensquilla skills search pdf
opensquilla skills view pptx
opensquilla skills view xlsx
Some document features require optional native/system dependencies. Use
opensquilla skills list and opensquilla doctor to check readiness.
Image Input and Generation
In terminal chat, send an image for analysis:
/image /path/to/screenshot.png Describe what is wrong with this UI.
Configure image generation:
opensquilla configure image-generation
Supported built-in image providers include OpenAI Images, OpenRouter Images,
and Qwen Token Plan (wan2.7-image / wan2.7-image-pro). Token Plan uses
QWEN_TOKEN_PLAN_API_KEY; its image-generation provider is distinct from the
Qwen model used to analyze image inputs.
Then ask for images in chat:
Generate a clean product mockup image for this landing page.
Image provider support depends on configured provider credentials, optional dependencies, and runtime policy.
Video Generation
After configuring video generation, ask
for a short clip in chat. The Agent may call video_generate with a text
prompt and optional duration, aspect ratio, resolution, or workspace filename.
The selected TokenRhythm or OpenRouter video model produces an MP4 in the
workspace, which the tool registers as an artifact for Web UI or supported
channel delivery. This release supports text-to-video only.
Generation may take several minutes. If the tool returns pending and a
job_id, the Agent can call video_status with that ID to continue checking
and deliver the finished MP4. video_status checks the existing job without
submitting another generation request. If submission has an unknown outcome
and no job ID was returned, do not automatically retry: a second request
could create and charge for another video. If the MP4 was saved but artifact
registration fails, the result reports generated_delivery_failed and keeps
the workspace path.
Once a provider returns a valid job ID, the Gateway retains its job record
even if the turn is stopped or times out. Recovery still requires that ID;
stopping before a tool result does not return it to the Agent automatically.
For non-owner callers, resuming a job requires the same Gateway process to
retain its job record and the same provider credential; a restart or credential
rotation can prevent recovery. A retained job keeps its original provider and
model even when the configured route changes. Its status tool remains available
to the same session if video generation is later disabled. Video tools are
unavailable to subagents in this release.
Text to Speech and Media Helpers
The media tool family includes image, video, PDF, and TTS helpers. Availability can depend on provider config, optional dependencies, and runtime policy.
Use media helpers when the requested output is naturally a file or asset rather than a plain text answer.
Channel Delivery
Channels differ in file-size limits, threading behavior, and upload APIs. If a channel cannot deliver an artifact directly, use the Web UI artifact card or session export as the recovery surface.
Self-contained HTML can be sent as a single file. HTML with saved local materials is sent as a ZIP containing the fixed published entry and resources. The export uses that saved version rather than reading newer working files. Missing or unsafe local materials prevent a complete export, and platform size limits apply to the file being uploaded.
Publication prepares a deliverable; it does not prove that a channel received it. Native delivery is confirmed by the existing outbox receipt. An uncertain send remains uncertain instead of being treated as success or automatically uploaded again.
For channel setup, see channels.md.
Troubleshooting
If an artifact does not appear:
-
Check the chat or CLI output for artifact events.
-
Open the Web UI session and inspect artifact cards.
-
Export the session if you need durable evidence:
opensquilla sessions export <session-key> -
Run
opensquilla doctorif a document or media dependency appears missing.
Docs index · Product guide · Improve this page · Report a docs issue