Agent Render Linking

Create browser links for artifacts rendered by agent-render.com.

Project context

Agent Render is:

• open source
• publicly hosted on Cloudflare Pages at agent-render.com
• self-hostable for people who want their own deployment
• meant to provide a zero-retention browser viewer for agent-shared artifacts

Source repository:

• https://github.com/baanish/agent-render

Core rule

Keep the artifact content in the URL fragment, not in normal query params.

Use this fragment shape:

#agent-render=v1.\x3Ccodec>.\x3Cpayload>                (plain | lz | deflate)
#agent-render=v1.arx.\x3CdictVersion>.\x3Cpayload>   (arx)

Supported codecs:

• plain: base64url-encoded JSON envelope
• lz: lz-string compressed JSON encoded for URL-safe transport
• deflate: deflate-compressed UTF-8 JSON bytes encoded as base64url
• arx: domain-dictionary substitution + brotli (quality 11) + base76/base1k/baseBMP encoding (~70% smaller than deflate with baseBMP). Fetch the shared dictionary from https://agent-render.com/arx-dictionary.json to apply substitutions locally before brotli compression. Three encoding tiers: baseBMP (~62k safe BMP code points, ~15.92 bits/char, best density), base1k (1774 Unicode code points U+00A1–U+07FF), and base76 (ASCII fallback). The encoder tries all three and picks the shortest.
• packed wire mode (p: 1) may be used automatically to shorten transport keys

Prefer:

1. shortest valid fragment for the target surface
2. codec priority arx -> deflate -> lz -> plain unless explicitly overridden
3. packed wire mode when available

Envelope shape

Use this JSON envelope:

{
  "v": 1,
  "codec": "plain",
  "title": "Artifact bundle title",
  "activeArtifactId": "artifact-1",
  "artifacts": [
    {
      "id": "artifact-1",
      "kind": "markdown",
      "title": "Weekly report",
      "filename": "weekly-report.md",
      "content": "# Report"
    }
  ]
}

Supported artifact kinds

Markdown

{
  "id": "report",
  "kind": "markdown",
  "title": "Weekly report",
  "filename": "weekly-report.md",
  "content": "# Report\
\
- Item one"
}

Code

{
  "id": "code",
  "kind": "code",
  "title": "viewer-shell.tsx",
  "filename": "viewer-shell.tsx",
  "language": "tsx",
  "content": "export function ViewerShell() {\
  return \x3Cmain />;\
}"
}

Diff

Prefer a real unified git patch in patch.

{
  "id": "patch",
  "kind": "diff",
  "title": "viewer-shell.tsx diff",
  "filename": "viewer-shell.patch",
  "patch": "diff --git a/viewer-shell.tsx b/viewer-shell.tsx\
--- a/viewer-shell.tsx\
+++ b/viewer-shell.tsx\
@@ -1 +1 @@\
-old\
+new\
",
  "view": "split"
}

Use view: "unified" or view: "split".

A single patch string may contain multiple diff --git sections.

CSV

{
  "id": "metrics",
  "kind": "csv",
  "title": "Metrics snapshot",
  "filename": "metrics.csv",
  "content": "name,value\
requests,42"
}

JSON

{
  "id": "manifest",
  "kind": "json",
  "title": "Manifest",
  "filename": "manifest.json",
  "content": "{\
  \"ready\": true\
}"
}

Multi-artifact bundles

Use multiple artifacts when the user should switch between related views.

Example cases:

• summary markdown + patch diff
• report markdown + raw CSV
• config JSON + related code file

Set activeArtifactId to the artifact that should open first.

Link construction

Construct the final URL as:

https://agent-render.com/#agent-render=v1.\x3Ccodec>.\x3Cpayload>                (plain | lz | deflate)
https://agent-render.com/#agent-render=v1.arx.\x3CdictVersion>.\x3Cpayload>       (arx)

For plain:

1. Serialize the envelope as compact JSON
2. Base64url-encode it
3. Append it after v1.plain.

For lz:

1. Serialize the envelope as compact JSON
2. Compress with lz-string URL-safe encoding
3. Append it after v1.lz.

For deflate:

1. Serialize the envelope as compact JSON (or packed wire form)
2. Encode JSON to UTF-8 bytes
3. Deflate the bytes
4. Base64url-encode the compressed bytes
5. Append it after v1.deflate.

Shared arx dictionary

The arx codec uses a substitution dictionary to replace common patterns with short byte sequences before brotli compression. The dictionary is served as a static JSON file:

• Endpoint: https://agent-render.com/arx-dictionary.json
• Pre-compressed: https://agent-render.com/arx-dictionary.json.br (brotli, ~929 bytes)

The dictionary contains two arrays:

• singleByteSlots: up to 25 patterns mapped to single control bytes (highest compression value)
• extendedSlots: additional patterns mapped to two-byte sequences (0x00 prefix + index)

To use the dictionary for local arx encoding:

1. Fetch https://agent-render.com/arx-dictionary.json
2. Apply substitutions in order: for each entry, replace all occurrences of the pattern in the serialized JSON envelope with its corresponding control byte(s)
3. Brotli-compress the substituted bytes at quality 11
4. Encode the compressed bytes using baseBMP (preferred, smallest), base1k (mid-tier), or base76 (ASCII fallback)
   • BaseBMP uses ~62k safe BMP code points (U+00A1–U+FFEF, skipping surrogates, combining marks, zero-width chars). Prefix the encoded string with U+FFF0 marker. ~15.92 bits/char
   • Base1k uses 1774 Unicode code points (U+00A1–U+07FF, skipping combining diacriticals and soft hyphen). ~10.79 bits/char
   • Base76 uses 77 ASCII fragment-safe characters — use this if the target surface cannot handle Unicode in URL fragments. ~6.27 bits/char
   • Try all three and pick the shortest
5. Prepend v1.arx.\x3CdictVersion>. to form the fragment payload (use the same dictionary version used for substitution)

The dictionary includes JSON envelope boilerplate patterns (like ","kind":"Markdown","content":"), JSON-escaped Markdown syntax, programming keywords, and common English words. The viewer loads the same dictionary on startup to reverse substitutions during decode.

If the dictionary fetch fails, fall back to deflate codec.

Practical limits

Respect these limits:

• target fragment budget: about 8,000 characters
• target decoded payload budget: about 200,000 characters
• strict Discord practical budget for linked text workflows: about 1,500 characters

If a link is getting too large:

1. try arx first, then deflate, then lz, then plain
2. allow packed wire mode
3. trim unnecessary prose or metadata
4. prefer a focused artifact over a bloated one
5. return a structured failure when the payload cannot fit the requested budget

Agent budget mode

When the caller provides a strict budget (for example 1,500 chars):

1. encode using all available candidates (arx/deflate/lz/plain, packed and non-packed)
2. choose the shortest fragment that is within budget
3. if no candidate fits, return the shortest fragment plus a clear budget failure explanation

Do not silently truncate content to force fit.

Formatting links in chat

Use platform-specific link text only on surfaces that support it cleanly.

Discord

Prefer standard Markdown links:

[Short summary](https://agent-render.com/#agent-render=...)

Examples:

• [Weekly report](https://agent-render.com/#agent-render=...)
• [Config diff](https://agent-render.com/#agent-render=...)
• [CSV snapshot](https://agent-render.com/#agent-render=...)

Telegram

Prefer HTML links because OpenClaw Telegram outbound text uses parse_mode: "HTML".

\x3Ca href="https://agent-render.com/#agent-render=...">Short summary\x3C/a>

Slack

Prefer Slack mrkdwn link syntax:

\x3Chttps://agent-render.com/#agent-render=...|Short summary>

All other OpenClaw chat surfaces

For WhatsApp, Signal, iMessage, Google Chat, IRC, LINE, and any other surface without reliable inline link-text formatting, do not force Markdown-style links.

Use:

• a short summary line first
• then the raw URL on its own line

If a provider later exposes a reliable native linked-text format, use that provider-specific syntax instead of generic Markdown.

Output style

When sharing a link:

• keep the summary short
• make the artifact title human-readable
• use filenames when they help the viewer
• do not narrate the transport details unless the user asks

Good defaults

• Prefer one strong artifact over many weak ones
• Prefer patch for diffs
• Prefer readable titles
• Prefer Markdown link text when supported
• Prefer shortest-by-measurement instead of human guesses
• Use budget-aware encoding for Discord-like constraints

Avoid

• Do not put raw artifact content in normal query params
• Do not upload artifact content to a server for this workflow
• Do not dump giant noisy bundles when a focused artifact is enough
• Do not invent unsupported fields unless the renderer has added them
• Do not handcraft packed envelopes manually if helper utilities are available; construct logical envelopes and let transport logic pack automatically