From 2d59edf13a25fbc8e47abfcc49f2b8b0f312447b Mon Sep 17 00:00:00 2001
From: praxagent <tim@praxagent.ai>
Date: Sat, 3 Oct 2026 11:50:48 -0700
Subject: [PATCH 1/2] =?UTF-8?q?feat:=20show=20the=20agent's=20artifacts=20?=
 =?UTF-8?q?=E2=80=94=20live,=20sandboxed,=20never=20on=20TeamWork's=20orig?=
 =?UTF-8?q?in?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A line '[artifact:<id>]' in a message or note renders the agent's page as a
live card (polls for new versions, full-screen view). The page comes from the
agent through /api/artifacts (behind TeamWork's login) and runs as srcdoc in
an iframe with sandbox='allow-scripts' and no allow-same-origin, under an
injected CSP with no network. Verified in headless Chromium: parent, cookies
and storage throw SecurityError, origin is null, fetch is refused.
Idea credit: Telepath's Television.
---
 docs/artifacts.md                             |  33 ++++++
 .../components/common/ArtifactCard.test.tsx   |  25 ++++
 .../src/components/common/ArtifactCard.tsx    | 111 ++++++++++++++++++
 .../src/components/common/MarkdownContent.tsx |  20 +++-
 frontend/src/hooks/useApi.ts                  |  48 ++++++++
 frontend/src/utils/artifacts.test.ts          |  47 ++++++++
 frontend/src/utils/artifacts.ts               |  90 ++++++++++++++
 src/teamwork/main.py                          |   2 +
 src/teamwork/routers/__init__.py              |   2 +
 src/teamwork/routers/artifacts.py             |  55 +++++++++
 tests/test_artifacts_proxy.py                 |  81 +++++++++++++
 11 files changed, 513 insertions(+), 1 deletion(-)
 create mode 100644 docs/artifacts.md
 create mode 100644 frontend/src/components/common/ArtifactCard.test.tsx
 create mode 100644 frontend/src/components/common/ArtifactCard.tsx
 create mode 100644 frontend/src/utils/artifacts.test.ts
 create mode 100644 frontend/src/utils/artifacts.ts
 create mode 100644 src/teamwork/routers/artifacts.py
 create mode 100644 tests/test_artifacts_proxy.py

diff --git a/docs/artifacts.md b/docs/artifacts.md
new file mode 100644
index 0000000..18e68a8
--- /dev/null
+++ b/docs/artifacts.md
@@ -0,0 +1,33 @@
+# Artifacts — the viewer
+
+An agent can make pages for you and keep them updated: a plan, a table, a
+chart, a small tool. Prax's `artifact_publish` is one example. The agent owns
+them (writing, storing, versioning). **TeamWork only shows them.**
+
+- **In chat and notes.** A line that is exactly `[artifact:<id>]` becomes a
+  live card. It reloads when the agent publishes a new version (polled every
+  5 s), and can be opened full screen.
+- **Where the page comes from.** `GET /api/artifacts/<id>` proxies to the
+  agent (`{PRAX_URL}/teamwork/artifacts/<id>`) behind TeamWork's login, like
+  the other agent panels. Unreachable → 503; unknown → 404.
+- **How it is rendered, and why.** An artifact was written by an agent,
+  possibly while it was reading untrusted content, and TeamWork's origin holds
+  your session. So a page never runs on TeamWork's origin:
+  - it is loaded as `srcdoc` in an iframe with `sandbox="allow-scripts"` and
+    **no** `allow-same-origin`, so its scripts run in an opaque origin;
+  - a Content-Security-Policy injected first in its `<head>` allows **no
+    network**, forms or base changes; the page's own tags can't loosen it,
+    because every policy applies;
+  - the frame sizes itself from a height message, accepted only from that
+    frame's own window.
+
+  Verified in headless Chromium (2026-10-03). From inside the frame:
+  `parent.document`, `document.cookie` and `localStorage` all throw
+  `SecurityError`, `self.origin` is `"null"`, and `fetch` is refused by
+  `connect-src 'none'`.
+- **Public links are the agent's business**, and need a person's decision.
+  TeamWork is never put behind a public tunnel (see
+  [security/exposure.md](security/exposure.md)).
+
+Idea credit: Telepath's Television
+([comparison](comparisons/television.md)).
diff --git a/frontend/src/components/common/ArtifactCard.test.tsx b/frontend/src/components/common/ArtifactCard.test.tsx
new file mode 100644
index 0000000..1d35d6c
--- /dev/null
+++ b/frontend/src/components/common/ArtifactCard.test.tsx
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { act, render } from '@testing-library/react';
+import { ArtifactFrame } from './ArtifactCard';
+
+describe('ArtifactFrame', () => {
+  it('runs the page sandboxed: scripts yes, TeamWork\'s origin no', () => {
+    const { container } = render(<ArtifactFrame html="<h1>Plan</h1>" title="Plan" />);
+    const frame = container.querySelector('iframe')!;
+    expect(frame.getAttribute('sandbox')).toBe('allow-scripts');
+    expect(frame.getAttribute('sandbox')).not.toContain('allow-same-origin');
+    expect(frame.getAttribute('srcdoc')).toContain('Content-Security-Policy');
+    expect(frame.getAttribute('srcdoc')).toContain('<h1>Plan</h1>');
+    expect(frame.getAttribute('referrerpolicy')).toBe('no-referrer');
+  });
+
+  it('ignores size messages from any window but its own', () => {
+    const { container } = render(<ArtifactFrame html="<p>x</p>" title="x" />);
+    const frame = container.querySelector('iframe')!;
+    const before = frame.style.height;
+    act(() => {
+      window.dispatchEvent(new MessageEvent('message', { data: { tvArtifactHeight: 9999 }, source: window }));
+    });
+    expect(frame.style.height).toBe(before);
+  });
+});
diff --git a/frontend/src/components/common/ArtifactCard.tsx b/frontend/src/components/common/ArtifactCard.tsx
new file mode 100644
index 0000000..fd4aab6
--- /dev/null
+++ b/frontend/src/components/common/ArtifactCard.tsx
@@ -0,0 +1,111 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { clsx } from 'clsx';
+import { Maximize2, Minimize2, LayoutTemplate } from 'lucide-react';
+import { useArtifact, useArtifactMeta } from '@/hooks/useApi';
+import { prepareArtifactDocument } from '@/utils/artifacts';
+
+/**
+ * A page the agent made, rendered in a sandboxed frame: `allow-scripts` and
+ * NOT `allow-same-origin`, so it runs in an opaque origin and cannot touch
+ * TeamWork's session, storage or /api/*; its CSP allows no network. See
+ * utils/artifacts.ts.
+ */
+export function ArtifactFrame({ html, title, maxHeight }: { html: string; title: string; maxHeight?: number }) {
+  const frameRef = useRef<HTMLIFrameElement>(null);
+  const [height, setHeight] = useState(240);
+  const doc = useMemo(() => prepareArtifactDocument(html), [html]);
+
+  useEffect(() => {
+    const onMessage = (event: MessageEvent) => {
+      // Only this frame's own window may size it, and only with a number.
+      if (event.source !== frameRef.current?.contentWindow) return;
+      const reported = (event.data as { tvArtifactHeight?: unknown })?.tvArtifactHeight;
+      if (typeof reported === 'number' && Number.isFinite(reported)) {
+        setHeight(Math.max(80, Math.min(reported, 20_000)));
+      }
+    };
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+  }, []);
+
+  return (
+    <iframe
+      ref={frameRef}
+      title={title}
+      sandbox="allow-scripts"
+      referrerPolicy="no-referrer"
+      srcDoc={doc}
+      className="w-full block bg-white"
+      style={{ height: maxHeight ? Math.min(height, maxHeight) : height, border: 0 }}
+    />
+  );
+}
+
+/** `[artifact:<id>]` in a message or note: the artifact, live, with a full-screen view. */
+export function ArtifactCard({ id }: { id: string }) {
+  const meta = useArtifactMeta(id);
+  const page = useArtifact(id, meta.data?.version);
+  const [expanded, setExpanded] = useState(false);
+
+  useEffect(() => {
+    if (!expanded) return;
+    const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') setExpanded(false); };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [expanded]);
+
+  if (meta.isError) {
+    return (
+      <div className="my-2 rounded-lg border border-gray-200 dark:border-gray-700 px-3 py-2 text-sm text-gray-500">
+        Artifact <code>{id}</code> is not available.
+      </div>
+    );
+  }
+  const title = meta.data?.title ?? 'Artifact';
+  const header = (
+    <div className="flex items-center gap-2 px-3 py-1.5 text-xs text-gray-600 dark:text-gray-300 border-b border-gray-200 dark:border-gray-700">
+      <LayoutTemplate className="w-3.5 h-3.5 shrink-0" aria-hidden />
+      <span className="font-medium truncate">{title}</span>
+      {meta.data && <span className="text-gray-400 shrink-0">v{meta.data.version}</span>}
+      <button
+        type="button"
+        onClick={() => setExpanded((v) => !v)}
+        className="ml-auto p-1 rounded hover:bg-gray-100 dark:hover:bg-gray-700"
+        aria-label={expanded ? 'Close full screen' : 'Open full screen'}
+        title={expanded ? 'Close (Esc)' : 'Open full screen'}
+      >
+        {expanded ? <Minimize2 className="w-3.5 h-3.5" /> : <Maximize2 className="w-3.5 h-3.5" />}
+      </button>
+    </div>
+  );
+  const body = page.data
+    ? <ArtifactFrame html={page.data.html} title={title} maxHeight={expanded ? undefined : 480} />
+    : <div className="p-4 text-center text-sm text-gray-500">Loading artifact…</div>;
+
+  return (
+    <>
+      <div className="my-2 rounded-lg overflow-hidden border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-900">
+        {header}
+        <div className="max-h-[480px] overflow-auto">{!expanded && body}</div>
+      </div>
+      {expanded && (
+        <div
+          role="dialog"
+          aria-modal="true"
+          aria-label={title}
+          className="fixed inset-0 z-50 bg-black/60 flex items-center justify-center p-2 md:p-8"
+          onClick={() => setExpanded(false)}
+        >
+          <div
+            className={clsx('w-full max-w-6xl h-full rounded-lg overflow-hidden flex flex-col',
+              'bg-white dark:bg-gray-900')}
+            onClick={(e) => e.stopPropagation()}
+          >
+            {header}
+            <div className="flex-1 overflow-auto">{body}</div>
+          </div>
+        </div>
+      )}
+    </>
+  );
+}
diff --git a/frontend/src/components/common/MarkdownContent.tsx b/frontend/src/components/common/MarkdownContent.tsx
index b323a87..0fed653 100644
--- a/frontend/src/components/common/MarkdownContent.tsx
+++ b/frontend/src/components/common/MarkdownContent.tsx
@@ -1,3 +1,5 @@
+import { ArtifactCard } from './ArtifactCard';
+import { splitArtifactMarkers } from '@/utils/artifacts';
 import ReactMarkdown from 'react-markdown';
 import { clsx } from 'clsx';
 import { ReactNode, createContext, useContext, useEffect, useId, useRef, useState } from 'react';
@@ -213,7 +215,23 @@ function preprocessContent(content: string): string {
  * - @mentions
  * - All standard markdown formatting
  */
-export function MarkdownContent({ content, className, darkMode: darkModeProp, onToggleTask }: MarkdownContentProps) {
+/**
+ * Markdown, plus the artifacts the agent shows with a line that is exactly
+ * `[artifact:<id>]` (rendered live, sandboxed — see ArtifactCard).
+ */
+export function MarkdownContent(props: MarkdownContentProps) {
+  const segments = splitArtifactMarkers(props.content);
+  if (!segments.some((s) => s.kind === 'artifact')) return <MarkdownBody {...props} />;
+  return (
+    <div className={props.className}>
+      {segments.map((s, i) => s.kind === 'artifact'
+        ? <ArtifactCard key={`a${i}-${s.id}`} id={s.id} />
+        : <MarkdownBody key={`m${i}`} {...props} className={undefined} content={s.text} />)}
+    </div>
+  );
+}
+
+function MarkdownBody({ content, className, darkMode: darkModeProp, onToggleTask }: MarkdownContentProps) {
   const storeDarkMode = useUIStore((s) => s.darkMode);
   const darkMode = darkModeProp ?? storeDarkMode;
   const processedContent = preprocessContent(content);
diff --git a/frontend/src/hooks/useApi.ts b/frontend/src/hooks/useApi.ts
index d9e39d8..91ec9bd 100644
--- a/frontend/src/hooks/useApi.ts
+++ b/frontend/src/hooks/useApi.ts
@@ -2699,6 +2699,54 @@ export function useAgentPlan(enabled: boolean = true) {
 }
 
 
+// Artifacts — pages the agent makes and keeps updating (see utils/artifacts.ts)
+
+export interface ArtifactMeta {
+  id: string;
+  title: string;
+  version: number;
+  created_at: string;
+  updated_at: string;
+  size: number;
+  space?: string;
+}
+
+export interface Artifact extends ArtifactMeta {
+  html: string;
+}
+
+/** The artifact's manifest, polled so a new version shows up on its own. */
+export function useArtifactMeta(id: string, enabled: boolean = true) {
+  return useQuery({
+    queryKey: ['artifact-meta', id],
+    queryFn: () => fetchJson<ArtifactMeta>(`/artifacts/${encodeURIComponent(id)}?meta=1`),
+    enabled: enabled && !!id,
+    refetchInterval: 5_000,
+    retry: false,
+  });
+}
+
+/** The full page for one version; refetched only when the version changes. */
+export function useArtifact(id: string, version: number | undefined) {
+  return useQuery({
+    queryKey: ['artifact', id, version],
+    queryFn: () => fetchJson<Artifact>(`/artifacts/${encodeURIComponent(id)}`),
+    enabled: !!id && version !== undefined,
+    staleTime: Infinity,
+    retry: false,
+  });
+}
+
+export function useArtifactList(enabled: boolean = true) {
+  return useQuery({
+    queryKey: ['artifacts'],
+    queryFn: () => fetchJson<{ artifacts: ArtifactMeta[] }>('/artifacts'),
+    enabled,
+    refetchInterval: 15_000,
+    retry: false,
+  });
+}
+
 // Claude Code Sessions
 
 export interface ClaudeCodeSession {
diff --git a/frontend/src/utils/artifacts.test.ts b/frontend/src/utils/artifacts.test.ts
new file mode 100644
index 0000000..a5011c2
--- /dev/null
+++ b/frontend/src/utils/artifacts.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { ARTIFACT_CSP, prepareArtifactDocument, splitArtifactMarkers } from './artifacts';
+
+describe('prepareArtifactDocument', () => {
+  it('puts the CSP first in an existing <head>', () => {
+    const doc = prepareArtifactDocument('<!doctype html><html><head><title>x</title></head><body>hi</body></html>');
+    const head = doc.indexOf('<head>');
+    expect(doc.slice(head + '<head>'.length).startsWith('<meta http-equiv="Content-Security-Policy"')).toBe(true);
+    expect(doc.indexOf('<meta')).toBeLessThan(doc.indexOf('<title>'));
+  });
+
+  it('adds a <head> when the page has only <html>', () => {
+    const doc = prepareArtifactDocument('<html><body>hi</body></html>');
+    expect(doc).toMatch(/<html><head><meta http-equiv="Content-Security-Policy"/);
+  });
+
+  it('wraps a fragment in a full document', () => {
+    const doc = prepareArtifactDocument('<h1>hi</h1>');
+    expect(doc.startsWith('<!doctype html><html><head><meta')).toBe(true);
+    expect(doc).toContain('<body><h1>hi</h1></body>');
+  });
+
+  it('allows no network', () => {
+    expect(ARTIFACT_CSP).toContain("default-src 'none'");
+    expect(ARTIFACT_CSP).toContain("connect-src 'none'");
+    expect(ARTIFACT_CSP).not.toMatch(/https?:/);
+  });
+});
+
+describe('splitArtifactMarkers', () => {
+  it('splits on lines that are exactly a marker', () => {
+    expect(splitArtifactMarkers('Here it is:\n[artifact:plan-1a2b3c]\nTell me what to change.')).toEqual([
+      { kind: 'markdown', text: 'Here it is:' },
+      { kind: 'artifact', id: 'plan-1a2b3c' },
+      { kind: 'markdown', text: 'Tell me what to change.' },
+    ]);
+  });
+
+  it('leaves inline mentions and code blocks alone', () => {
+    const text = 'see [artifact:a-1] inline\n```\n[artifact:b-2]\n```';
+    expect(splitArtifactMarkers(text)).toEqual([{ kind: 'markdown', text }]);
+  });
+
+  it('rejects ids that are not artifact ids', () => {
+    expect(splitArtifactMarkers('[artifact:../etc]')).toEqual([{ kind: 'markdown', text: '[artifact:../etc]' }]);
+  });
+});
diff --git a/frontend/src/utils/artifacts.ts b/frontend/src/utils/artifacts.ts
new file mode 100644
index 0000000..7974ebf
--- /dev/null
+++ b/frontend/src/utils/artifacts.ts
@@ -0,0 +1,90 @@
+/**
+ * Artifacts: pages the agent makes and keeps updating.
+ *
+ * TeamWork only displays them, and never on its own origin: the origin holds
+ * the session and can call /api/*, and an artifact may have been written while
+ * the agent was reading untrusted content. So a page is rendered as `srcdoc`
+ * in an iframe with `sandbox="allow-scripts"` and NO `allow-same-origin`:
+ * scripts run, in an opaque origin, with a Content-Security-Policy that
+ * allows no network. Idea credit: Telepath's Television.
+ */
+
+/** No network, no forms, no navigation of the parent; inline code only. */
+export const ARTIFACT_CSP = [
+  "default-src 'none'",
+  "script-src 'unsafe-inline'",
+  "style-src 'unsafe-inline'",
+  'img-src data: blob:',
+  'font-src data:',
+  'media-src data: blob:',
+  "connect-src 'none'",
+  "form-action 'none'",
+  "base-uri 'none'",
+].join('; ');
+
+/**
+ * Posts the page's height to the parent so the frame can size itself; the
+ * parent only accepts it from that frame's own window (see ArtifactFrame).
+ */
+const RESIZE_SCRIPT =
+  '<script>(function(){function h(){parent.postMessage({tvArtifactHeight:' +
+  'Math.ceil(document.documentElement.scrollHeight)},"*")}' +
+  'addEventListener("load",h);new ResizeObserver(h).observe(document.documentElement)})();</script>';
+
+const META = `<meta http-equiv="Content-Security-Policy" content="${ARTIFACT_CSP}">`;
+
+/**
+ * The page as the frame should load it: the CSP meta first in <head> (so the
+ * page's own tags cannot loosen it — every policy applies, the strictest
+ * wins), plus the resize reporter.
+ */
+export function prepareArtifactDocument(html: string): string {
+  const inject = META + RESIZE_SCRIPT;
+  const head = /<head(\s[^>]*)?>/i.exec(html);
+  if (head) {
+    const at = head.index + head[0].length;
+    return html.slice(0, at) + inject + html.slice(at);
+  }
+  const htmlTag = /<html(\s[^>]*)?>/i.exec(html);
+  if (htmlTag) {
+    const at = htmlTag.index + htmlTag[0].length;
+    return html.slice(0, at) + `<head>${inject}</head>` + html.slice(at);
+  }
+  return `<!doctype html><html><head>${inject}</head><body>${html}</body></html>`;
+}
+
+export type ContentSegment =
+  | { kind: 'markdown'; text: string }
+  | { kind: 'artifact'; id: string };
+
+const MARKER = /^\s*\[artifact:([a-z0-9][a-z0-9-]{0,63})\]\s*$/;
+
+/**
+ * Split message or note content on lines that are exactly `[artifact:<id>]`,
+ * which the agent writes to show an artifact. A marker inside a code block is
+ * left as text.
+ */
+export function splitArtifactMarkers(content: string): ContentSegment[] {
+  const out: ContentSegment[] = [];
+  let buffer: string[] = [];
+  let inFence = false;
+  const flush = () => {
+    if (buffer.length) {
+      const text = buffer.join('\n');
+      if (text.trim()) out.push({ kind: 'markdown', text });
+      buffer = [];
+    }
+  };
+  for (const line of content.split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) inFence = !inFence;
+    const m = inFence ? null : MARKER.exec(line);
+    if (m) {
+      flush();
+      out.push({ kind: 'artifact', id: m[1] });
+    } else {
+      buffer.push(line);
+    }
+  }
+  flush();
+  return out;
+}
diff --git a/src/teamwork/main.py b/src/teamwork/main.py
index c6ba326..a42f2ce 100644
--- a/src/teamwork/main.py
+++ b/src/teamwork/main.py
@@ -29,6 +29,7 @@
 from teamwork.models import init_db, AsyncSessionLocal
 from teamwork.routers import (
     agent_plan_router,
+    artifacts_router,
     agents_router,
     browser_router,
     claude_code_router,
@@ -170,6 +171,7 @@ async def send_with_nosniff(message) -> None:
 
 # Include routers
 app.include_router(agent_plan_router, prefix="/api")
+app.include_router(artifacts_router, prefix="/api")
 app.include_router(observability_router, prefix="/api")
 app.include_router(memory_router, prefix="/api")
 app.include_router(claude_code_router, prefix="/api")
diff --git a/src/teamwork/routers/__init__.py b/src/teamwork/routers/__init__.py
index 489071d..107cc32 100644
--- a/src/teamwork/routers/__init__.py
+++ b/src/teamwork/routers/__init__.py
@@ -1,6 +1,7 @@
 """API routers for TeamWork."""
 
 from teamwork.routers.agent_plan import router as agent_plan_router
+from teamwork.routers.artifacts import router as artifacts_router
 from teamwork.routers.agents import router as agents_router
 from teamwork.routers.browser import router as browser_router
 from teamwork.routers.claude_code import router as claude_code_router
@@ -22,6 +23,7 @@
 
 __all__ = [
     "agent_plan_router",
+    "artifacts_router",
     "agents_router",
     "browser_router",
     "claude_code_router",
diff --git a/src/teamwork/routers/artifacts.py b/src/teamwork/routers/artifacts.py
new file mode 100644
index 0000000..8d4c18c
--- /dev/null
+++ b/src/teamwork/routers/artifacts.py
@@ -0,0 +1,55 @@
+"""Artifacts: pages the agent makes and keeps updating (Prax: ARTIFACTS_ENABLED).
+
+TeamWork only displays them. The page comes from the agent
+(``GET {PRAX_URL}/teamwork/artifacts/<id>``) and the frontend renders it in a
+sandboxed frame — scripts run, but in an opaque origin with no network — never
+on TeamWork's own origin, which holds the session. See
+``docs/comparisons/television.md`` and backlog #1.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Query
+
+from teamwork.config import settings
+from teamwork.routers.prax import prax_client
+
+router = APIRouter(prefix="/artifacts", tags=["artifacts"])
+_logger = logging.getLogger(__name__)
+
+_ID = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
+
+
+async def _get(path: str, params: dict | None = None) -> Any:
+    prax_url = settings.prax_url
+    if not prax_url:
+        raise HTTPException(status_code=503, detail="No agent is connected (PRAX_URL)")
+    try:
+        async with prax_client(timeout=10.0) as client:
+            resp = await client.get(f"{prax_url.rstrip('/')}/teamwork/artifacts{path}",
+                                    params=params)
+    except Exception as exc:  # noqa: BLE001 - agent unreachable
+        _logger.debug("artifacts proxy %s failed: %s", path, exc)
+        raise HTTPException(status_code=503, detail="The agent is not reachable") from exc
+    if resp.status_code == 404:
+        raise HTTPException(status_code=404, detail="No such artifact, or artifacts are off")
+    if resp.status_code >= 400:
+        raise HTTPException(status_code=502, detail=f"The agent answered {resp.status_code}")
+    return resp.json()
+
+
+@router.get("")
+async def list_artifacts():
+    """Every artifact's manifest, newest first."""
+    return await _get("")
+
+
+@router.get("/{artifact_id}")
+async def get_artifact(artifact_id: str, meta: bool = Query(False)):
+    """One artifact (manifest + ``html``); ``?meta=1`` omits the page."""
+    if not _ID.match(artifact_id):
+        raise HTTPException(status_code=404, detail="No such artifact")
+    return await _get(f"/{artifact_id}", params={"meta": "1"} if meta else None)
diff --git a/tests/test_artifacts_proxy.py b/tests/test_artifacts_proxy.py
new file mode 100644
index 0000000..1a60dec
--- /dev/null
+++ b/tests/test_artifacts_proxy.py
@@ -0,0 +1,81 @@
+"""The artifacts proxy: TeamWork shows the agent's pages, it does not make them.
+
+Failures are HTTP failures (see test_proxy_error_contract), so the viewer can
+say "not available" instead of rendering a body with no page in it.
+"""
+from __future__ import annotations
+
+import httpx
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from teamwork.routers import artifacts as mod
+
+PAGE = {"id": "plan-1a2b3c", "title": "Plan", "version": 2, "html": "<h1>Plan</h1>"}
+
+
+class _Client:
+    def __init__(self, responder):
+        self.responder = responder
+        self.calls = []
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        return False
+
+    async def get(self, url, params=None):
+        self.calls.append((url, params))
+        return self.responder(url, params)
+
+
+@pytest.fixture
+def app(monkeypatch):
+    monkeypatch.setattr(mod.settings, "prax_url", "http://prax.test")
+    a = FastAPI()
+    a.include_router(mod.router, prefix="/api")
+    return a
+
+
+def _use(monkeypatch, responder):
+    client = _Client(responder)
+    monkeypatch.setattr(mod, "prax_client", lambda timeout: client)
+    return client
+
+
+def test_it_passes_the_page_through(app, monkeypatch):
+    calls = _use(monkeypatch, lambda url, params: httpx.Response(200, json=PAGE))
+    resp = TestClient(app).get("/api/artifacts/plan-1a2b3c")
+    assert resp.status_code == 200 and resp.json()["html"] == "<h1>Plan</h1>"
+    assert calls.calls == [("http://prax.test/teamwork/artifacts/plan-1a2b3c", None)]
+
+
+def test_meta_asks_the_agent_for_the_manifest_only(app, monkeypatch):
+    calls = _use(monkeypatch, lambda url, params: httpx.Response(200, json={**PAGE, "html": None}))
+    TestClient(app).get("/api/artifacts/plan-1a2b3c?meta=1")
+    assert calls.calls[0][1] == {"meta": "1"}
+
+
+def test_unknown_artifact_is_404(app, monkeypatch):
+    _use(monkeypatch, lambda url, params: httpx.Response(404, json={"error": "no such artifact"}))
+    assert TestClient(app).get("/api/artifacts/nope-000000").status_code == 404
+
+
+def test_a_bad_id_never_reaches_the_agent(app, monkeypatch):
+    calls = _use(monkeypatch, lambda url, params: httpx.Response(200, json=PAGE))
+    assert TestClient(app).get("/api/artifacts/UPPER..x").status_code == 404
+    assert calls.calls == []
+
+
+def test_an_unreachable_agent_is_503(app, monkeypatch):
+    def boom(url, params):
+        raise httpx.ConnectError("refused")
+    _use(monkeypatch, boom)
+    assert TestClient(app).get("/api/artifacts").status_code == 503
+
+
+def test_no_agent_configured_is_503(app, monkeypatch):
+    monkeypatch.setattr(mod.settings, "prax_url", "")
+    assert TestClient(app).get("/api/artifacts").status_code == 503

From 2c5dd76f3660730d2c1b0cf6af3f96abaebe6abc Mon Sep 17 00:00:00 2001
From: praxagent <tim@praxagent.ai>
Date: Sat, 3 Oct 2026 14:12:25 -0700
Subject: [PATCH 2/2] docs: agents treat TeamWork as private, so the deployer
 has to keep it private
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An agent shows its work in TeamWork without asking (Prax: TeamWork is
trusted, a public link needs a person's decision). That holds only if
TeamWork is deployed privately — login on, private reach — and no agent can
check it from the inside.
---
 docs/artifacts.md         |  3 ++-
 docs/security/exposure.md | 18 ++++++++++++++++++
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/docs/artifacts.md b/docs/artifacts.md
index 18e68a8..8a9db76 100644
--- a/docs/artifacts.md
+++ b/docs/artifacts.md
@@ -26,7 +26,8 @@ them (writing, storing, versioning). **TeamWork only shows them.**
   `SecurityError`, `self.origin` is `"null"`, and `fetch` is refused by
   `connect-src 'none'`.
 - **Public links are the agent's business**, and need a person's decision.
-  TeamWork is never put behind a public tunnel (see
+  Inside TeamWork an artifact is private only as long as TeamWork is: keep its
+  login on and reach it privately (see
   [security/exposure.md](security/exposure.md)).
 
 Idea credit: Telepath's Television
diff --git a/docs/security/exposure.md b/docs/security/exposure.md
index f03c81d..9922cfd 100644
--- a/docs/security/exposure.md
+++ b/docs/security/exposure.md
@@ -20,6 +20,24 @@ guess is obscurity, not access control: URLs leak through browser history,
 screenshots, shared links, logs and referrer headers, and tunnel hostnames are
 scanned.
 
+## Agents treat TeamWork as private — so it has to be
+
+An agent connected to TeamWork shows you its work here without asking: files,
+notes, pages it made, its terminal and browser. That is the right default only
+because TeamWork is meant to be private. Prax, for one, enforces exactly this
+split: anything in TeamWork is fine, but putting something on a public link
+needs a person's explicit decision every time
+([Prax: public exposure](https://github.com/praxagent/prax/blob/main/docs/security/public-exposure.md)).
+
+That trust is something **you** provide when you deploy TeamWork. No agent can
+check it from the inside. If TeamWork is reachable by people you don't trust,
+everything an agent shows you here is reachable by them too. So:
+
+- keep the login on (`INTERNAL_API_KEY`, below);
+- reach TeamWork privately (loopback, `tailscale serve`, an SSH tunnel);
+- if you do put it behind a public tunnel, follow the checklist at the end
+  first.
+
 ## What is open without a login
 
 Out of the box, TeamWork has **no login** (`INTERNAL_API_KEY` is empty and