@lazyingart/agintiflow 0.20.125 → 0.20.127

package/README.md

@@ -114,6 +114,16 @@ aginti web --port 3210
 # opens http://127.0.0.1:3210, or the next available port
 ```
 
+Check or prepare the Docker/LaTeX sandbox explicitly:
+
+```bash
+aginti docker status
+aginti docker setup
+aginti docker install-host --yes   # Ubuntu host only; explicit opt-in
+```
+
+AgInTiFlow does not silently install Docker during npm postinstall. Docker changes host services and permissions, so host installation is explicit. Normal mode can install packages and TeX/Python dependencies inside the Docker sandbox. Danger mode is trusted host mode for tasks that really need host package managers or system services.
+
 Run without live model credentials for smoke tests:
 
 ```bash

package/docs/runtime-modes-and-autonomy.md

@@ -43,6 +43,15 @@ Docker package installs are safe when they match the sandbox contract.
 - OS package installs such as `apt-get install htop` affect only the current short-lived command container unless the Docker image is rebuilt.
 - To make OS packages portable, add them to `docker/sandbox.Dockerfile` and rebuild with `scripts/setup-agent-toolchain-docker.sh`.
 
+Use the built-in Docker setup command for the normal sandbox/toolchain path:
+
+```bash
+aginti docker status
+aginti docker setup
+```
+
+`aginti docker setup` builds or verifies the companion sandbox image and checks Node, npm, Python, matplotlib/numpy, `latexmk`, `pdflatex`, git, and ripgrep inside Docker. If host Docker itself is missing, AgInTiFlow prints platform-specific install guidance. `aginti docker install-host --yes` is only an explicit opt-in helper for supported Ubuntu hosts; npm postinstall does not silently install Docker or mutate host services.
+
 This is why a task can safely install Python packages in Docker, but cannot keep an interactive tmux server alive inside a one-shot Docker command.
 
 ## Permission Contract

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.125",
+  "version": "0.20.127",
   "type": "module",
   "description": "AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-aware intelligence, software automation, and industrial workflows.",
   "license": "Apache-2.0",
@@ -57,6 +57,7 @@
     "scripts/smoke-canvas-artifacts.js",
     "scripts/smoke-cli-chat.js",
     "scripts/smoke-coding-tools.js",
+    "scripts/smoke-docker-command.js",
     "scripts/smoke-dynamic-step-budget.js",
     "scripts/smoke-capabilities.js",
     "scripts/smoke-auto-update.js",
@@ -94,6 +95,7 @@
     "smoke:auth": "node scripts/smoke-auth.js",
     "smoke:canvas-artifacts": "node scripts/smoke-canvas-artifacts.js",
     "smoke:cli-chat": "node scripts/smoke-cli-chat.js",
+    "smoke:docker-command": "node scripts/smoke-docker-command.js",
     "smoke:skills": "node scripts/smoke-skills.js",
     "smoke:skillmesh": "node scripts/smoke-skillmesh.js",
     "smoke:toolchain-docker": "node scripts/smoke-toolchain-docker.js",
@@ -112,7 +114,7 @@
     "postinstall": "node scripts/postinstall-webapp.js",
     "supervision:seed": "node scripts/seed-supervised-homework.js",
     "storage:migrate": "node bin/aginti-cli.js storage migrate",
-    "test": "npm run check && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:auth && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:auth && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:cli-chat && npm run smoke:inbox",
     "pack:dry-run": "npm pack --dry-run",
     "smoke:capabilities": "node scripts/smoke-capabilities.js"
   },

package/public/app.js

@@ -2061,6 +2061,12 @@ function resetArtifactViewer() {
   artifactViewerBodyEl.innerHTML = `<p class="subtle">${t("artifactViewerEmpty")}</p>`;
 }
 
+function artifactRawUrl(artifactId, { download = false } = {}) {
+  if (!currentSessionId || !artifactId) return "";
+  const base = `/api/sessions/${encodeURIComponent(currentSessionId)}/artifacts/${encodeURIComponent(artifactId)}/raw`;
+  return download ? `${base}?download=1` : base;
+}
+
 function renderArtifactShell() {
   renderArtifactBadge();
   renderArtifactList();
@@ -2075,23 +2081,40 @@ function renderArtifactContent(content) {
   artifactViewerTitleEl.textContent = content.title || item?.title || t("artifactViewerEmptyTitle");
   artifactViewerMetaEl.textContent = [content.path || item?.path, item ? artifactLabel(item) : ""].filter(Boolean).join(" · ");
   artifactViewerKindEl.textContent = content.kind || item?.kind || "";
+  const streamedUrl = content.url || (content.id ? artifactRawUrl(content.id) : "");
+  const downloadUrl = content.downloadUrl || (content.id ? artifactRawUrl(content.id, { download: true }) : "");
+  const renderUrl = content.dataUrl || streamedUrl;
 
-  if (content.dataUrl && (content.kind === "pdf" || content.mime === "application/pdf")) {
+  if (renderUrl && (content.kind === "pdf" || content.mime === "application/pdf")) {
     artifactViewerBodyEl.innerHTML = `
-      <iframe class="artifact-pdf-frame" src="${content.dataUrl}" title="${escapeHtml(content.title || "Artifact PDF")}"></iframe>
+      <iframe class="artifact-pdf-frame" src="${renderUrl}" title="${escapeHtml(content.title || "Artifact PDF")}"></iframe>
     `;
     return;
   }
 
-  if (content.dataUrl) {
+  if (renderUrl && (content.kind === "image" || String(content.mime || "").startsWith("image/"))) {
     artifactViewerBodyEl.innerHTML = `
       <figure class="artifact-image-frame">
-        <img class="artifact-preview-image" src="${content.dataUrl}" alt="${escapeHtml(content.title || "Artifact image")}" />
+        <img class="artifact-preview-image" src="${renderUrl}" alt="${escapeHtml(content.title || "Artifact image")}" />
       </figure>
     `;
     return;
   }
 
+  if ((content.tooLargeForInline || content.binary) && streamedUrl) {
+    artifactViewerBodyEl.innerHTML = `
+      <div class="artifact-large-file">
+        <strong>${escapeHtml(content.preview || "Artifact is available as a streamed file.")}</strong>
+        <p>${escapeHtml(content.path || item?.path || content.title || "Generated artifact")}</p>
+        <div class="artifact-file-actions">
+          <a class="secondary-button" href="${streamedUrl}" target="_blank" rel="noreferrer">Open preview</a>
+          <a class="secondary-button" href="${downloadUrl}" download="${escapeHtml(artifactDownloadName(item, content))}">Download</a>
+        </div>
+      </div>
+    `;
+    return;
+  }
+
   const text = typeof content.text === "string" ? content.text : "";
   if (content.kind === "markdown" || /markdown/i.test(content.mime || "")) {
     artifactViewerBodyEl.innerHTML = `<div class="artifact-markdown markdown-body">${renderMarkdown(text)}</div>`;
@@ -2153,6 +2176,21 @@ async function downloadArtifact(artifactId) {
     const data = await response.json().catch(() => ({}));
     if (!response.ok) throw new Error(data.error || t("artifactDownloadFailed"));
 
+    if ((data.downloadUrl || data.url) && !data.dataUrl && typeof data.text !== "string") {
+      const link = document.createElement("a");
+      link.href = data.downloadUrl || artifactRawUrl(artifactId, { download: true }) || data.url;
+      link.download = artifactDownloadName(item, data);
+      document.body.append(link);
+      link.click();
+      link.remove();
+
+      markArtifactRead(artifactId);
+      renderArtifactBadge();
+      renderArtifactList();
+      artifactStatusEl.textContent = t("artifactDownloadReady");
+      return;
+    }
+
     const blob = data.dataUrl
       ? blobFromDataUrl(data.dataUrl)
       : new Blob([typeof data.text === "string" ? data.text : JSON.stringify(data, null, 2)], {

package/public/styles.css

@@ -1602,6 +1602,29 @@ button.danger {
   background: white;
 }
 
+.artifact-large-file {
+  display: grid;
+  gap: 10px;
+  align-content: start;
+  margin: 0;
+  padding: 18px;
+  border: 1px solid var(--line);
+  border-radius: 16px;
+  background: rgba(255, 255, 255, 0.72);
+}
+
+.artifact-large-file p {
+  margin: 0;
+  color: var(--muted);
+  overflow-wrap: anywhere;
+}
+
+.artifact-file-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
 .artifact-editor {
   min-height: 100%;
   height: 100%;

package/references/agintiflow-aaps-slogan-subtext-v3.md

@@ -14,7 +14,7 @@ AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-a
 
 Project-oriented programming for agentic workflows.
 
-AAPS is a project oriented and prompt-native programming language and visual studio for turning prompts into structured, verifiable pipelines. It connects wet and dry experiments, hardware and software, and human intent with executable agent work through tasks, typed inputs, declared outputs, validation gates, recovery steps, and durable artifacts.
+AAPS is a prompt-native programming language and visual studio for turning prompts into structured, verifiable pipelines. It connects wet and dry experiments, hardware and software, and human intent with executable agent work through tasks, typed inputs, declared outputs, validation gates, recovery steps, and durable artifacts.
 
 ## Shorter Version
 

package/scripts/smoke-canvas-artifacts.js

@@ -1,7 +1,13 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { buildArtifacts, normalizeCanvasPayload, persistCanvasPayloadFile, readArtifactContent } from "../src/artifact-tunnel.js";
+import {
+  buildArtifacts,
+  normalizeCanvasPayload,
+  persistCanvasPayloadFile,
+  readArtifactContent,
+  resolveArtifactFile,
+} from "../src/artifact-tunnel.js";
 import { SessionStore } from "../src/session-store.js";
 
 async function main() {
@@ -54,6 +60,45 @@ async function main() {
   if (!content.ok) throw new Error(content.error || "persisted artifact could not be read");
   if (!String(content.text || "").includes("Durable report")) throw new Error("persisted artifact content mismatch");
 
+  const largeImagePath = path.join(workspace, "large-preview.png");
+  const pngHeader = Buffer.from("89504e470d0a1a0a", "hex");
+  await fs.writeFile(largeImagePath, Buffer.concat([pngHeader, Buffer.alloc(4_200_000)]));
+  const largeNormalized = normalizeCanvasPayload(
+    {
+      title: "Large preview image",
+      kind: "image",
+      path: "large-preview.png",
+      selected: true,
+    },
+    config
+  );
+  if (!largeNormalized.ok) throw new Error(largeNormalized.reason || "large image canvas payload normalization failed");
+  const largePersisted = await persistCanvasPayloadFile(largeNormalized.payload, { config, store });
+  if (!largePersisted.ok) throw new Error(largePersisted.reason || "large image canvas artifact persistence failed");
+  if (!largePersisted.payload.artifactPersisted) throw new Error("large image was not persisted into session artifacts");
+
+  const largeEvents = [
+    {
+      timestamp: new Date().toISOString(),
+      type: "canvas.item",
+      data: {
+        ...largePersisted.payload,
+        commandCwd: workspace,
+      },
+    },
+  ];
+  const { items: largeItems } = buildArtifacts({ sessionId: store.sessionId, events: largeEvents, store });
+  const largeContent = await readArtifactContent(largeItems[0], { store, config });
+  if (!largeContent.ok) throw new Error(largeContent.error || "large artifact metadata could not be read");
+  if (largeContent.dataUrl) throw new Error("large artifact should not be inlined as a data URL");
+  if (!largeContent.url || !largeContent.downloadUrl || !largeContent.tooLargeForInline) {
+    throw new Error("large artifact did not expose streamed preview URLs");
+  }
+  const largeFile = await resolveArtifactFile(largeItems[0], { store, config });
+  if (!largeFile.ok || largeFile.size <= 4_000_000 || largeFile.mime !== "image/png") {
+    throw new Error("large artifact file resolver returned invalid metadata");
+  }
+
   const missing = await persistCanvasPayloadFile({ ...normalized.payload, path: "missing.png" }, { config, store });
   if (missing.ok) throw new Error("missing canvas path should fail persistence");
 

package/scripts/smoke-cli-chat.js

@@ -219,6 +219,7 @@ try {
     "helpScouts",
     "helpRouting",
     "helpProvider",
+    "helpDocker",
     "helpDockerOn",
     "helpDockerOff",
     "helpLatex",

package/scripts/smoke-docker-command.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "agintiflow-docker-command-"));
+
+try {
+  const { stdout } = await execFileAsync(process.execPath, [path.join(repoRoot, "bin/aginti-cli.js"), "docker", "status", "--json", "--cwd", tempRoot], {
+    cwd: tempRoot,
+    env: {
+      ...process.env,
+      AGINTIFLOW_NO_WEB_AUTO_START: "1",
+    },
+    timeout: 20000,
+    maxBuffer: 1024 * 1024,
+  });
+  const parsed = JSON.parse(stdout);
+  assert.equal(parsed.ok, true, "docker status command should return ok envelope");
+  assert.equal(parsed.summary.workspace, tempRoot, "docker status should honor --cwd");
+  assert.equal(typeof parsed.summary.dockerAvailable, "boolean", "docker status should include docker availability");
+  assert(parsed.summary.install?.command, "docker status should include install guidance");
+
+  const install = await execFileAsync(process.execPath, [path.join(repoRoot, "bin/aginti-cli.js"), "docker", "install-host", "--json"], {
+    cwd: tempRoot,
+    timeout: 20000,
+    maxBuffer: 1024 * 1024,
+  });
+  const installPlan = JSON.parse(install.stdout);
+  assert.equal(typeof installPlan.supported, "boolean", "install-host plan should state support");
+  assert(installPlan.command, "install-host plan should include a command or guidance");
+
+  console.log("docker command smoke ok");
+} finally {
+  await fs.rm(tempRoot, { recursive: true, force: true });
+}

package/scripts/smoke-web-api.js

@@ -350,6 +350,37 @@ try {
     throw new Error("artifact content endpoint did not return renderable content");
   }
 
+  const largeSessionId = "large-artifact-smoke";
+  const largeStore = new SessionStore(paths.globalSessionsDir, largeSessionId, sessionStoreOptions(runtimeDir, largeSessionId));
+  await largeStore.ensure();
+  const largeCanvasDir = path.join(largeStore.artifactsDir, "canvas");
+  await fs.mkdir(largeCanvasDir, { recursive: true });
+  const largeImagePath = path.join(largeCanvasDir, "large-image.png");
+  await fs.writeFile(largeImagePath, Buffer.concat([Buffer.from("89504e470d0a1a0a", "hex"), Buffer.alloc(4_200_000)]));
+  await largeStore.appendEvent("canvas.item", {
+    artifactId: "large-image",
+    title: "Large streamed image",
+    kind: "image",
+    path: "large-image.png",
+    sessionFilePath: largeImagePath,
+    selected: true,
+  });
+  const largeArtifacts = await fetchJson(`/api/sessions/${encodeURIComponent(largeSessionId)}/artifacts`);
+  if (!largeArtifacts.items?.some((item) => item.id === "large-image")) {
+    throw new Error("large artifact endpoint did not list session artifact");
+  }
+  const largeContent = await fetchJson(`/api/sessions/${encodeURIComponent(largeSessionId)}/artifacts/large-image`);
+  if (!largeContent.tooLargeForInline || !largeContent.url || largeContent.dataUrl) {
+    throw new Error("large artifact metadata did not switch to streamed preview");
+  }
+  const rawResponse = await fetch(`${baseUrl}/api/sessions/${encodeURIComponent(largeSessionId)}/artifacts/large-image/raw`);
+  if (!rawResponse.ok) throw new Error(`large artifact raw endpoint failed: ${rawResponse.status}`);
+  if (!/^image\/png\b/i.test(rawResponse.headers.get("content-type") || "")) {
+    throw new Error("large artifact raw endpoint did not preserve image content type");
+  }
+  const rawBytes = await rawResponse.arrayBuffer();
+  if (rawBytes.byteLength <= 4_000_000) throw new Error("large artifact raw endpoint returned truncated content");
+
   const deleted = await fetchJson(`/api/sessions/${encodeURIComponent(runStart.sessionId)}`, {
     method: "DELETE",
   });
@@ -384,6 +415,7 @@ try {
           "/api/workspace/changes",
           "/api/sessions/:id/artifacts",
           "/api/sessions/:id/artifacts/:artifactId",
+          "/api/sessions/:id/artifacts/:artifactId/raw",
           "POST /api/sessions/:id/artifacts/select",
         ],
         provider: run.provider,

package/src/artifact-tunnel.js

@@ -60,6 +60,16 @@ function mimeForPath(filePath) {
   return IMAGE_MIME_BY_EXT.get(ext) || BINARY_RENDER_MIME_BY_EXT.get(ext) || "text/plain; charset=utf-8";
 }
 
+function isRenderableBinaryMime(mime) {
+  return String(mime || "").startsWith("image/") || mime === "application/pdf";
+}
+
+function artifactRawUrl(item, download = false) {
+  if (!item?.sessionId || !item?.id) return "";
+  const base = `/api/sessions/${encodeURIComponent(item.sessionId)}/artifacts/${encodeURIComponent(item.id)}/raw`;
+  return download ? `${base}?download=1` : base;
+}
+
 function safeCanvasFilename(artifactId, filePath) {
   const rawBase = path.basename(String(filePath || "artifact"));
   const safeBase = rawBase
@@ -285,24 +295,13 @@ export function findArtifact(items, artifactId) {
   return items.find((item) => item.id === artifactId) || null;
 }
 
-export async function readArtifactContent(item, { store, config }) {
+export async function resolveArtifactFile(item, { store, config } = {}) {
   if (!item) {
     return { ok: false, error: "Artifact not found." };
   }
 
-  if (item.ref?.type === "inline") {
-    return {
-      ok: true,
-      id: item.id,
-      kind: item.kind,
-      title: item.title,
-      path: item.path || "",
-      mime: item.mime || "text/plain; charset=utf-8",
-      text: redactSensitiveText(String(item.ref.text || "")),
-    };
-  }
-
   if (item.ref?.type === "session-file") {
+    if (!store?.sessionDir) return { ok: false, error: "Artifact session store is unavailable." };
     const absolutePath = path.resolve(item.ref.path);
     if (!isInside(store.sessionDir, absolutePath)) {
       return { ok: false, error: "Artifact path is outside this session." };
@@ -311,32 +310,14 @@ export async function readArtifactContent(item, { store, config }) {
     const stat = await fs.stat(absolutePath).catch(() => null);
     if (!stat?.isFile()) return { ok: false, error: "Artifact file is missing." };
     const mime = mimeForPath(absolutePath);
-    const isBinaryRenderable = mime.startsWith("image/") || mime === "application/pdf";
-    const maxBytes = isBinaryRenderable ? MAX_ARTIFACT_IMAGE_BYTES : MAX_ARTIFACT_TEXT_BYTES;
-    if (stat.size > maxBytes) return { ok: false, error: "Artifact is too large to preview safely." };
-
-    const buffer = await fs.readFile(absolutePath);
-    if (isBinaryRenderable) {
-      return {
-        ok: true,
-        id: item.id,
-        kind: mime === "application/pdf" ? "pdf" : "image",
-        title: item.title,
-        path: item.path || "",
-        mime,
-        dataUrl: `data:${mime};base64,${buffer.toString("base64")}`,
-      };
-    }
-
-    if (buffer.includes(0)) return { ok: false, error: "Binary artifact cannot be rendered as text." };
     return {
       ok: true,
-      id: item.id,
-      kind: item.kind,
+      absolutePath,
+      size: stat.size,
+      mime,
+      kind: mime === "application/pdf" ? "pdf" : mime.startsWith("image/") ? "image" : item.kind,
       title: item.title,
       path: item.path || "",
-      mime,
-      text: redactSensitiveText(buffer.toString("utf8")),
     };
   }
 
@@ -350,33 +331,87 @@ export async function readArtifactContent(item, { store, config }) {
     const target = resolveWorkspacePath(itemConfig, item.ref.path);
     const stat = await fs.stat(target.absolutePath).catch(() => null);
     if (!stat?.isFile()) return { ok: false, error: "Workspace file is missing." };
-
     const mime = mimeForPath(target.absolutePath);
-    const isBinaryRenderable = mime.startsWith("image/") || mime === "application/pdf";
+    return {
+      ok: true,
+      absolutePath: target.absolutePath,
+      size: stat.size,
+      mime,
+      kind: mime === "application/pdf" ? "pdf" : mime.startsWith("image/") ? "image" : item.kind,
+      title: item.title,
+      path: item.path || "",
+    };
+  }
+
+  return { ok: false, error: "Artifact has no readable file." };
+}
+
+export async function readArtifactContent(item, { store, config }) {
+  if (!item) {
+    return { ok: false, error: "Artifact not found." };
+  }
+
+  if (item.ref?.type === "inline") {
+    return {
+      ok: true,
+      id: item.id,
+      kind: item.kind,
+      title: item.title,
+      path: item.path || "",
+      mime: item.mime || "text/plain; charset=utf-8",
+      text: redactSensitiveText(String(item.ref.text || "")),
+    };
+  }
+
+  if (item.ref?.type === "session-file" || item.ref?.type === "workspace-file") {
+    const resolved = await resolveArtifactFile(item, { store, config });
+    if (!resolved.ok) return resolved;
+
+    const isBinaryRenderable = isRenderableBinaryMime(resolved.mime);
     const maxBytes = isBinaryRenderable ? MAX_ARTIFACT_IMAGE_BYTES : MAX_ARTIFACT_TEXT_BYTES;
-    if (stat.size > maxBytes) return { ok: false, error: "Workspace file is too large to preview safely." };
+    const url = artifactRawUrl(item);
+    const downloadUrl = artifactRawUrl(item, true);
+    const base = {
+      ok: true,
+      id: item.id,
+      kind: resolved.kind,
+      title: item.title,
+      path: item.path || "",
+      mime: resolved.mime,
+      size: resolved.size,
+      url,
+      downloadUrl,
+    };
+
+    if (resolved.size > maxBytes) {
+      return {
+        ...base,
+        tooLargeForInline: true,
+        preview: isBinaryRenderable
+          ? "Large renderable artifact is available through the streamed artifact endpoint."
+          : "Large artifact is available through the streamed artifact endpoint.",
+      };
+    }
 
-    const buffer = await fs.readFile(target.absolutePath);
+    const buffer = await fs.readFile(resolved.absolutePath);
     if (isBinaryRenderable) {
       return {
-        ok: true,
-        id: item.id,
-        kind: mime === "application/pdf" ? "pdf" : "image",
-        title: item.title,
-        path: item.path || "",
-        mime,
-        dataUrl: `data:${mime};base64,${buffer.toString("base64")}`,
+        ...base,
+        dataUrl: `data:${resolved.mime};base64,${buffer.toString("base64")}`,
+      };
+    }
+
+    if (buffer.includes(0)) {
+      return {
+        ...base,
+        binary: true,
+        preview: "Binary artifact is available through the streamed artifact endpoint.",
       };
     }
 
-    if (buffer.includes(0)) return { ok: false, error: "Binary workspace file cannot be rendered as text." };
     return {
-      ok: true,
-      id: item.id,
+      ...base,
       kind: item.kind,
-      title: item.title,
-      path: item.path || "",
-      mime,
       text: redactSensitiveText(buffer.toString("utf8")),
     };
   }

package/src/cli.js

@@ -38,9 +38,11 @@ import { handleAapsCliCommand } from "./aaps-adapter.js";
 import { formatInstructionTemplateList, normalizeInstructionTemplate } from "./behavior-contract.js";
 import { applyPermissionMode, normalizePermissionMode } from "./permission-modes.js";
 import { ensureAgintiWebApp } from "./web-autostart.js";
+import { dockerHostInstallPlan, formatDockerSetupText, summarizeDockerSetup } from "./docker-setup.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
 import readline from "node:readline/promises";
 import * as readlineRaw from "node:readline";
 
@@ -716,12 +718,104 @@ function exitOnUnknownOptions(parsed) {
 
 function printUsage() {
   console.log(
-    'Usage: aginti [chat] OR aginti init [--template minimal|disciplined|coding|research|writing|design|aaps|supervision] OR aginti web [--port 3210] OR aginti update OR aginti models OR aginti aaps [status|init|files|validate|compile|check|run] OR aginti skills [query] OR aginti skillmesh [status|off|record|share|sync|serve|service] OR aginti housekeeping [--json] OR aginti auth [deepseek|openai|qwen|venice|grsai] OR aginti resume [--all-sessions] [latest|<session-id>] ["prompt"] OR aginti --remove-empty-sessions OR aginti --remove-sessions OR aginti queue <session-id> "message" OR aginti [--no-auto-update] [-s safe|normal|danger] [--language en|ja|zh-Hans|zh-Hant|ko|fr|es|ar|vi|de|ru] [--image] [--latex] [--scs|--scs auto|--no-scs] [--dynamic-steps auto|on|off] [--routing smart|fast|complex|manual] [--provider deepseek|openai|qwen|venice|mock] [--model MODEL] [--route-model MODEL] [--main-model MODEL] [--spare-model MODEL --spare-reasoning medium] [--aux-provider grsai|venice --aux-model MODEL] [--sandbox-mode host|docker-readonly|docker-workspace] [--package-install-policy block|prompt|allow] [--approve-package-installs] [--allow-shell|--no-shell] [--allow-file-tools|--no-file-tools] [--web-search|--no-web-search] [--parallel-scouts|--no-parallel-scouts --scout-count 1..10] [--allow-auxiliary-tools|--no-auxiliary-tools] [--allow-wrappers --wrapper codex --wrapper-model gpt-5.5] [--list-models|--list-routes] "your task"'
+    'Usage: aginti [chat] OR aginti init [--template minimal|disciplined|coding|research|writing|design|aaps|supervision] OR aginti web [--port 3210] OR aginti docker [status|setup|install-host] OR aginti update OR aginti models OR aginti aaps [status|init|files|validate|compile|check|run] OR aginti skills [query] OR aginti skillmesh [status|off|record|share|sync|serve|service] OR aginti housekeeping [--json] OR aginti auth [deepseek|openai|qwen|venice|grsai] OR aginti resume [--all-sessions] [latest|<session-id>] ["prompt"] OR aginti --remove-empty-sessions OR aginti --remove-sessions OR aginti queue <session-id> "message" OR aginti [--no-auto-update] [-s safe|normal|danger] [--language en|ja|zh-Hans|zh-Hant|ko|fr|es|ar|vi|de|ru] [--image] [--latex] [--scs|--scs auto|--no-scs] [--dynamic-steps auto|on|off] [--routing smart|fast|complex|manual] [--provider deepseek|openai|qwen|venice|mock] [--model MODEL] [--route-model MODEL] [--main-model MODEL] [--spare-model MODEL --spare-reasoning medium] [--aux-provider grsai|venice --aux-model MODEL] [--sandbox-mode host|docker-readonly|docker-workspace] [--package-install-policy block|prompt|allow] [--approve-package-installs] [--allow-shell|--no-shell] [--allow-file-tools|--no-file-tools] [--web-search|--no-web-search] [--parallel-scouts|--no-parallel-scouts --scout-count 1..10] [--allow-auxiliary-tools|--no-auxiliary-tools] [--allow-wrappers --wrapper codex --wrapper-model gpt-5.5] [--list-models|--list-routes] "your task"'
   );
   console.log("Permission shortcuts: -s safe asks before writes/setup; -s normal allows current-project writes and Docker setup; -s danger enables trusted host/full-access mode.");
   console.log(`Languages: ${["en", "ja", "zh-Hans", "zh-Hant", "ko", "fr", "es", "ar", "vi", "de", "ru"].map((code) => `${code}=${languageLabel(code)}`).join(", ")}`);
 }
 
+function parseDockerCommandArgs(argv = [], fallbackCwd = process.cwd()) {
+  const result = {
+    action: "status",
+    json: false,
+    yes: false,
+    commandCwd: fallbackCwd,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--json") {
+      result.json = true;
+      continue;
+    }
+    if (arg === "--yes" || arg === "-y") {
+      result.yes = true;
+      continue;
+    }
+    if (arg === "--cwd") {
+      result.commandCwd = readOption(argv, index) || result.commandCwd;
+      index += 1;
+      continue;
+    }
+    if (!arg.startsWith("-") && result.action === "status") {
+      result.action = arg;
+      continue;
+    }
+  }
+  return result;
+}
+
+function runInherited(command, args = [], options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: "inherit", ...options });
+    child.on("close", (code) => resolve(Number(code || 0)));
+    child.on("error", (error) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      resolve(1);
+    });
+  });
+}
+
+async function handleDockerCommand(argv = [], { commandCwd = process.cwd() } = {}) {
+  const parsed = parseDockerCommandArgs(argv, commandCwd);
+  const config = loadConfig(
+    {
+      goal: "docker setup",
+      commandCwd: parsed.commandCwd,
+      sandboxMode: "docker-workspace",
+      packageInstallPolicy: "allow",
+      provider: "mock",
+      routingMode: "manual",
+    },
+    { packageDir, baseDir: parsed.commandCwd }
+  );
+  const action = String(parsed.action || "status").toLowerCase();
+
+  if (["install", "install-host", "host-install"].includes(action)) {
+    const plan = dockerHostInstallPlan(packageDir);
+    if (parsed.json) {
+      console.log(JSON.stringify(plan, null, 2));
+      return;
+    }
+    if (!plan.supported) {
+      console.log(formatDockerSetupText(summarizeDockerSetup({ status: await getDockerSandboxStatus(config), packageDir })));
+      console.log("");
+      console.log("Host Docker auto-install is intentionally not run on this platform.");
+      console.log(`Recommended path: ${plan.command}`);
+      return;
+    }
+    if (!parsed.yes) {
+      console.log("Host Docker install requires explicit confirmation because it changes system packages/services.");
+      console.log(`Run: aginti docker install-host --yes`);
+      console.log(`Script: ${plan.command}`);
+      return;
+    }
+    const exitCode = await runInherited("bash", [plan.command], { cwd: packageDir });
+    process.exitCode = exitCode;
+    return;
+  }
+
+  const buildImage = ["setup", "build", "preflight", "latex", "toolchain"].includes(action);
+  const result = buildImage
+    ? await runDockerPreflight(config, { buildImage: true })
+    : { ok: true, status: await getDockerSandboxStatus(config), checks: [] };
+  const summary = summarizeDockerSetup({ status: result.status, preflight: buildImage ? result : null, packageDir });
+  if (parsed.json) {
+    console.log(JSON.stringify({ ok: buildImage ? result.ok : true, summary, result }, null, 2));
+    return;
+  }
+  console.log(formatDockerSetupText(summary));
+}
+
 function stripLeadingGlobalOptions(argv = []) {
   let index = 0;
   const options = {
@@ -1607,6 +1701,11 @@ export async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (commandArgv[0] === "docker") {
+    await handleDockerCommand(commandArgv.slice(1), { commandCwd });
+    return;
+  }
+
   if (commandArgv.includes("--remove-empty-sessions") || commandArgv[0] === "remove-empty-sessions") {
     await handleRemoveSessionsCommand({ emptyOnly: true });
     return;

package/src/docker-setup.js

@@ -0,0 +1,107 @@
+import os from "node:os";
+import path from "node:path";
+import { platformInfo, platformLabel, platformSetupHints } from "./platform.js";
+
+function latexStatusFromChecks(checks = []) {
+  const latexChecks = checks.filter((check) => /latexmk|pdflatex/i.test(check.command || ""));
+  if (!latexChecks.length) return "unchecked";
+  return latexChecks.every((check) => check.ok) ? "ready" : "missing";
+}
+
+export function dockerHostInstallPlan(packageDir = process.cwd(), info = platformInfo()) {
+  const hints = platformSetupHints(info);
+  const script = path.join(packageDir, "scripts", "install-docker-ubuntu.sh");
+  if (info.isMac) {
+    return {
+      supported: false,
+      platform: platformLabel(info),
+      command: "Install Docker Desktop or Colima, then run: aginti docker setup",
+      hints,
+    };
+  }
+  if (info.isWindows && !info.isWsl) {
+    return {
+      supported: false,
+      platform: platformLabel(info),
+      command: "Use WSL2 with Docker Desktop WSL integration, then run: aginti docker setup inside WSL",
+      hints,
+    };
+  }
+  if (info.isLinux && info.linuxFamily === "debian" && /ubuntu/i.test(`${info.linuxId} ${info.distro}`)) {
+    return {
+      supported: true,
+      platform: platformLabel(info),
+      command: script,
+      hints,
+    };
+  }
+  return {
+    supported: false,
+    platform: platformLabel(info),
+    command: "Install a Docker-compatible engine with your OS package manager, then run: aginti docker setup",
+    hints,
+  };
+}
+
+export function summarizeDockerSetup({ status, preflight = null, packageDir = process.cwd() } = {}) {
+  const info = platformInfo();
+  const install = dockerHostInstallPlan(packageDir, info);
+  const checks = preflight?.checks || [];
+  const failedChecks = checks.filter((check) => !check.ok);
+  const latex = latexStatusFromChecks(checks);
+  return {
+    platform: platformLabel(info),
+    sandboxMode: status?.sandboxMode || "unknown",
+    packageInstallPolicy: status?.packageInstallPolicy || "unknown",
+    dockerAvailable: Boolean(status?.dockerAvailable),
+    image: status?.image || "agintiflow-sandbox:latest",
+    imageReady: Boolean(status?.imageReady),
+    dockerfileExists: Boolean(status?.dockerfileExists),
+    workspace: status?.workspace || process.cwd(),
+    persistentDocker: status?.persistentDocker || {},
+    latex,
+    preflightOk: preflight ? Boolean(preflight.ok && failedChecks.length === 0) : undefined,
+    failedChecks: failedChecks.map((check) => check.command || check.error || "unknown"),
+    install,
+  };
+}
+
+export function formatDockerSetupText(summary = {}) {
+  const lines = [
+    "AgInTiFlow Docker setup",
+    `platform=${summary.platform || `${os.type()} (${process.arch})`}`,
+    `sandbox=${summary.sandboxMode || "unknown"} installs=${summary.packageInstallPolicy || "unknown"}`,
+    `docker=${summary.dockerAvailable ? "available" : "missing"} image=${summary.image || "agintiflow-sandbox:latest"} ${
+      summary.imageReady ? "ready" : "not-ready"
+    }`,
+    `dockerfile=${summary.dockerfileExists ? "present" : "missing"}`,
+    `workspace=${summary.workspace || process.cwd()}`,
+  ];
+
+  if (summary.persistentDocker?.root || summary.persistentDocker?.env) {
+    lines.push(`persistent=${summary.persistentDocker.root || path.dirname(summary.persistentDocker.env)}`);
+  }
+  if (summary.latex && summary.latex !== "unchecked") lines.push(`latex=${summary.latex}`);
+  if (summary.preflightOk !== undefined) lines.push(`preflight=${summary.preflightOk ? "passed" : "failed"}`);
+  if (summary.failedChecks?.length) {
+    lines.push(`failedChecks=${summary.failedChecks.join(", ")}`);
+  }
+
+  lines.push("");
+  if (!summary.dockerAvailable) {
+    lines.push("Docker is not available.");
+    lines.push(`Install path: ${summary.install?.command || "Install Docker, then run: aginti docker setup"}`);
+  } else if (!summary.imageReady || summary.preflightOk === false) {
+    lines.push("Next: aginti docker setup");
+  } else {
+    lines.push("Docker sandbox is ready for normal-mode package setup and LaTeX/PDF work.");
+  }
+
+  if (summary.install?.hints?.length) {
+    lines.push("");
+    lines.push("Platform notes:");
+    for (const hint of summary.install.hints) lines.push(`- ${hint}`);
+  }
+
+  return lines.join("\n");
+}

package/src/i18n.js

@@ -146,6 +146,7 @@ const TRANSLATIONS = {
     helpRouting: "Set routing: smart, fast, complex, manual.",
     helpProvider: "Open provider selector, or set deepseek/openai/qwen/venice/mock.",
     helpPermissionMode: "Switch safe/normal/danger permission posture for this session.",
+    helpDocker: "Inspect or prepare the Docker sandbox/toolchain.",
     helpDockerOn: "Use docker-workspace with approved package installs.",
     helpDockerOff: "Use host shell policy.",
     helpLatex: "Use the LaTeX/PDF profile in Docker with a larger step budget.",
@@ -197,6 +198,7 @@ const TRANSLATIONS = {
     helpScouts: "並列 DeepSeek スカウトを有効化し数を設定します。",
     helpRouting: "routing を smart、fast、complex、manual に設定します。",
     helpProvider: "プロバイダ選択を開くか deepseek/openai/qwen/venice/mock を設定します。",
+    helpDocker: "Docker サンドボックス/ツールチェーンを確認または準備します。",
     helpDockerOn: "承認済みパッケージインストール付き docker-workspace を使います。",
     helpDockerOff: "ホストシェルポリシーを使います。",
     helpLatex: "Docker で LaTeX/PDF プロファイルと大きめのステップ数を使います。",
@@ -248,6 +250,7 @@ const TRANSLATIONS = {
     helpScouts: "启用并设置并行 DeepSeek scouts 数量。",
     helpRouting: "设置 routing: smart、fast、complex、manual。",
     helpProvider: "打开 provider 选择器，或设置 deepseek/openai/qwen/venice/mock。",
+    helpDocker: "检查或准备 Docker 沙箱/工具链。",
     helpDockerOn: "使用允许安装包的 docker-workspace。",
     helpDockerOff: "使用主机 shell 策略。",
     helpLatex: "在 Docker 中使用 LaTeX/PDF profile 和更大步骤数。",
@@ -299,6 +302,7 @@ const TRANSLATIONS = {
     helpScouts: "啟用並設定並行 DeepSeek scouts 數量。",
     helpRouting: "設定 routing: smart、fast、complex、manual。",
     helpProvider: "開啟 provider 選擇器，或設定 deepseek/openai/qwen/venice/mock。",
+    helpDocker: "檢查或準備 Docker 沙箱/工具鏈。",
     helpDockerOn: "使用允許安裝套件的 docker-workspace。",
     helpDockerOff: "使用主機 shell 策略。",
     helpLatex: "在 Docker 中使用 LaTeX/PDF profile 和較大步數。",
@@ -353,6 +357,7 @@ const FALLBACKS = {
     helpScouts: "병렬 DeepSeek 스카우트를 켜고 수를 설정합니다.",
     helpRouting: "routing 을 smart, fast, complex, manual 로 설정합니다.",
     helpProvider: "provider 선택기를 열거나 deepseek/openai/qwen/venice/mock 을 설정합니다.",
+    helpDocker: "Docker 샌드박스/툴체인을 확인하거나 준비합니다.",
     helpDockerOn: "승인된 패키지 설치가 가능한 docker-workspace 를 사용합니다.",
     helpDockerOff: "호스트 shell 정책을 사용합니다.",
     helpLatex: "Docker 에서 LaTeX/PDF 프로필과 더 큰 단계 예산을 사용합니다.",
@@ -404,6 +409,7 @@ const FALLBACKS = {
     helpScouts: "Activer les scouts DeepSeek parallèles et régler leur nombre.",
     helpRouting: "Définir le routage: smart, fast, complex, manual.",
     helpProvider: "Ouvrir le sélecteur provider, ou définir deepseek/openai/qwen/venice/mock.",
+    helpDocker: "Inspecter ou préparer le sandbox/la toolchain Docker.",
     helpDockerOn: "Utiliser docker-workspace avec installations de paquets approuvées.",
     helpDockerOff: "Utiliser la politique shell hôte.",
     helpLatex: "Utiliser le profil LaTeX/PDF dans Docker avec plus d'étapes.",
@@ -455,6 +461,7 @@ const FALLBACKS = {
     helpScouts: "Activar scouts DeepSeek paralelos y configurar cantidad.",
     helpRouting: "Configurar routing: smart, fast, complex, manual.",
     helpProvider: "Abrir selector provider, o configurar deepseek/openai/qwen/venice/mock.",
+    helpDocker: "Inspeccionar o preparar el sandbox/toolchain Docker.",
     helpDockerOn: "Usar docker-workspace con instalaciones aprobadas.",
     helpDockerOff: "Usar política de shell host.",
     helpLatex: "Usar perfil LaTeX/PDF en Docker con más pasos.",
@@ -506,6 +513,7 @@ const FALLBACKS = {
     helpScouts: "تفعيل كشافات DeepSeek المتوازية وتحديد عددها.",
     helpRouting: "تعيين routing: smart أو fast أو complex أو manual.",
     helpProvider: "فتح محدد provider أو تعيين deepseek/openai/qwen/venice/mock.",
+    helpDocker: "فحص أو تجهيز صندوق Docker والأدوات.",
     helpDockerOn: "استخدام docker-workspace مع تثبيت حزم معتمد.",
     helpDockerOff: "استخدام سياسة shell المضيف.",
     helpLatex: "استخدام ملف LaTeX/PDF في Docker مع ميزانية خطوات أكبر.",
@@ -557,6 +565,7 @@ const FALLBACKS = {
     helpScouts: "Bật DeepSeek scouts song song và đặt số lượng.",
     helpRouting: "Đặt routing: smart, fast, complex, manual.",
     helpProvider: "Mở bộ chọn provider, hoặc đặt deepseek/openai/qwen/venice/mock.",
+    helpDocker: "Kiểm tra hoặc chuẩn bị sandbox/toolchain Docker.",
     helpDockerOn: "Dùng docker-workspace với cài package đã duyệt.",
     helpDockerOff: "Dùng chính sách shell host.",
     helpLatex: "Dùng profile LaTeX/PDF trong Docker với ngân sách bước lớn hơn.",
@@ -608,6 +617,7 @@ const FALLBACKS = {
     helpScouts: "Parallele DeepSeek-Scouts aktivieren und Anzahl setzen.",
     helpRouting: "Routing setzen: smart, fast, complex, manual.",
     helpProvider: "Provider-Auswahl öffnen oder deepseek/openai/qwen/venice/mock setzen.",
+    helpDocker: "Docker-Sandbox/Toolchain prüfen oder vorbereiten.",
     helpDockerOn: "docker-workspace mit genehmigten Paketinstallationen verwenden.",
     helpDockerOff: "Host-Shell-Policy verwenden.",
     helpLatex: "LaTeX/PDF-Profil in Docker mit größerem Schrittbudget verwenden.",
@@ -659,6 +669,7 @@ const FALLBACKS = {
     helpScouts: "Включить параллельных DeepSeek scouts и задать количество.",
     helpRouting: "Задать routing: smart, fast, complex, manual.",
     helpProvider: "Открыть выбор provider или задать deepseek/openai/qwen/venice/mock.",
+    helpDocker: "Проверить или подготовить Docker sandbox/toolchain.",
     helpDockerOn: "Использовать docker-workspace с одобренными установками пакетов.",
     helpDockerOff: "Использовать политику host shell.",
     helpLatex: "Использовать профиль LaTeX/PDF в Docker с большим числом шагов.",

package/src/interactive-cli.js

@@ -13,6 +13,8 @@ import {
   sessionStoreOptions,
 } from "./project.js";
 import { normalizePackageInstallPolicy, normalizeSandboxMode } from "./command-policy.js";
+import { getDockerSandboxStatus, runDockerPreflight } from "./docker-sandbox.js";
+import { formatDockerSetupText, summarizeDockerSetup } from "./docker-setup.js";
 import { defaultMaxStepsForProfile, normalizeTaskProfile } from "./task-profiles.js";
 import { recommendedMaxStepsForTask } from "./engineering-guidance.js";
 import { normalizeAuthProvider, runAuthWizard, shouldPromptForDeepSeek } from "./auth-onboarding.js";
@@ -889,8 +891,7 @@ function printHelp() {
       `  ${command("/routing <mode>", "Set routing: smart, fast, complex, manual.", "helpRouting")}`,
       `  ${command("/provider [name]", "Open provider selector, or set deepseek/openai/qwen/venice/mock.", "helpProvider")}`,
       `  ${command("/safe | /normal | /danger", "Switch permission posture for this session.", "helpPermissionMode")}`,
-      `  ${command("/docker on", "Use docker-workspace with approved package installs.", "helpDockerOn")}`,
-      `  ${command("/docker off", "Use host shell policy.", "helpDockerOff")}`,
+      `  ${command("/docker [status|setup|on|off]", "Inspect or prepare the Docker sandbox/toolchain.", "helpDocker")}`,
       `  ${command("/latex on", "Use the LaTeX/PDF profile in Docker with a larger step budget.", "helpLatex")}`,
       `  ${command("/installs block|prompt|allow", "Set package install policy.", "helpInstalls")}`,
       `  ${command("/cwd <path>", "Change command workspace.", "helpCwd")}`,
@@ -3619,8 +3620,35 @@ async function handleCommand(line, state, packageDir) {
       state.sandboxMode = "host";
       state.packageInstallPolicy = "prompt";
       printSystemLine("docker=off sandbox=host installs=prompt");
+    } else if (value === "status" || value === "") {
+      const config = loadConfig(
+        {
+          ...state,
+          goal: "docker status",
+          commandCwd: state.commandCwd || process.cwd(),
+          sandboxMode: state.sandboxMode || "docker-workspace",
+          packageInstallPolicy: state.packageInstallPolicy || "allow",
+        },
+        { packageDir, baseDir: state.commandCwd || process.cwd() }
+      );
+      const status = await getDockerSandboxStatus(config);
+      printAgentMessage(formatDockerSetupText(summarizeDockerSetup({ status, packageDir })));
+    } else if (value === "setup" || value === "preflight" || value === "build" || value === "latex") {
+      const config = loadConfig(
+        {
+          ...state,
+          goal: "docker setup",
+          commandCwd: state.commandCwd || process.cwd(),
+          sandboxMode: "docker-workspace",
+          packageInstallPolicy: "allow",
+        },
+        { packageDir, baseDir: state.commandCwd || process.cwd() }
+      );
+      printSystemLine("docker=setup starting");
+      const result = await runDockerPreflight(config, { buildImage: true });
+      printAgentMessage(formatDockerSetupText(summarizeDockerSetup({ status: result.status, preflight: result, packageDir })));
     } else {
-      printAgentMessage("Usage: /docker on OR /docker off");
+      printAgentMessage("Usage: /docker status OR /docker setup OR /docker on OR /docker off");
     }
     return true;
   }

package/web.js

@@ -1,3 +1,4 @@
+import { createReadStream } from "node:fs";
 import fs from "node:fs/promises";
 import express from "express";
 import path from "node:path";
@@ -43,6 +44,7 @@ import {
   countUnreadArtifacts,
   findArtifact,
   readArtifactContent,
+  resolveArtifactFile,
   serializeArtifacts,
 } from "./src/artifact-tunnel.js";
 
@@ -75,6 +77,17 @@ function isSafeSessionId(sessionId) {
   return /^[A-Za-z0-9._:-]+$/.test(String(sessionId || "")) && !String(sessionId || "").includes("..");
 }
 
+function safeDownloadFilename(value) {
+  const basename = path.basename(String(value || "artifact").replace(/\\/g, "/"));
+  return (
+    basename
+      .replace(/[\r\n"\\]+/g, "_")
+      .replace(/^\.+/, "")
+      .replace(/[^A-Za-z0-9._ -]+/g, "-")
+      .slice(0, 120) || "artifact"
+  );
+}
+
 function mapEventLogs(events) {
   return events.map((event) => ({
     at: event.timestamp,
@@ -877,6 +890,39 @@ app.get("/api/sessions/:sessionId/artifacts/:artifactId", async (req, res) => {
   res.json(content);
 });
 
+app.get("/api/sessions/:sessionId/artifacts/:artifactId/raw", async (req, res) => {
+  const bundle = await loadArtifactBundle(req.params.sessionId);
+  if (bundle.error) {
+    res.status(bundle.status || 500).json({ error: bundle.error });
+    return;
+  }
+
+  const artifact = findArtifact(bundle.items, req.params.artifactId);
+  const file = await resolveArtifactFile(artifact, bundle);
+  if (!file.ok) {
+    res.status(artifact ? 400 : 404).json({ error: file.error || "Artifact not found." });
+    return;
+  }
+
+  const filename = safeDownloadFilename(file.path || file.title || file.absolutePath);
+  const disposition = req.query.download === "1" ? "attachment" : "inline";
+  res.setHeader("Content-Type", file.mime || "application/octet-stream");
+  res.setHeader("Content-Length", String(file.size));
+  res.setHeader("Content-Disposition", `${disposition}; filename="${filename}"`);
+  res.setHeader("Cache-Control", "private, max-age=0, no-cache");
+  res.setHeader("X-Content-Type-Options", "nosniff");
+
+  const stream = createReadStream(file.absolutePath);
+  stream.on("error", (error) => {
+    if (!res.headersSent) {
+      res.status(500).json({ error: error instanceof Error ? error.message : String(error) });
+      return;
+    }
+    res.destroy(error);
+  });
+  stream.pipe(res);
+});
+
 app.post("/api/sessions/:sessionId/artifacts/select", async (req, res) => {
   const bundle = await loadArtifactBundle(req.params.sessionId);
   if (bundle.error) {