feat(pxpipe): PXPIPE token saver — multimodal prompt compression (#2465)

Add pxpipe as an experimental fifth Token Saver: Claude-format request
bodies above a configurable size threshold are rendered as dense PNGs
via the pxpipe-proxy library API (transformAnthropicMessages) before
dispatch, cutting estimated input tokens by ~35-60% on token-dense
contexts. Integration follows the Headroom pattern: applied to the final
body in chatCore just before dispatch, fail-open on any error/timeout.

Managed npm install into DATA_DIR/pxpipe, dynamic loader with per-version
cache-bust, JSONL event log with rotation, /api/pxpipe/* endpoints, Token
Saver card (marked experimental) + /dashboard/pxpipe page, and per-request
Activated/Skipped annotation in Request Details. Disabled by default.
This commit is contained in:
Elio Bonfim Júnior
2026-07-10 16:10:42 +07:00
committed by decolua
parent e1f3399b73
commit dcf1927f22
26 changed files with 1324 additions and 7 deletions
@@ -0,0 +1,283 @@
"use client";
import { useState, useEffect, useCallback } from "react";
import {
AreaChart,
Area,
XAxis,
YAxis,
CartesianGrid,
Tooltip,
ResponsiveContainer,
} from "recharts";
import { Card, Button } from "@/shared/components";
const fmtTokens = (n) => {
if (n >= 1000000) return `${(n / 1000000).toFixed(2)}M`;
if (n >= 1000) return `${(n / 1000).toFixed(1)}K`;
return String(n || 0);
};
const fmtUptime = (ms) => {
if (!ms || ms <= 0) return "—";
const m = Math.floor(ms / 60000);
const h = Math.floor(m / 60);
return h > 0 ? `${h}h${String(m % 60).padStart(2, "0")}m` : `${m}m`;
};
const WINDOW_TABS = [
{ id: "today", label: "Today" },
{ id: "yesterday", label: "Yesterday" },
{ id: "last7d", label: "7 days" },
{ id: "last30d", label: "30 days" },
{ id: "all", label: "All time" },
];
const REASON_LABELS = {
applied: "Prompt exceeded threshold",
below_threshold: "Below size threshold",
not_profitable: "Compression not profitable",
below_min_chars: "Below minimum chars",
below_min_tokens: "Below minimum tokens",
unsupported_model: "Model not in allowlist",
unsupported_format: "Non-Claude request format",
timeout: "Compression timed out",
transform_error: "Transform error",
passthrough: "Passthrough",
disabled: "Disabled",
not_installed: "Not installed",
};
function SummaryCard({ label, value, sub, tone }) {
return (
<Card className="p-4">
<p className="text-xs text-text-muted uppercase tracking-wide">{label}</p>
<p className={`text-xl font-semibold mt-1 ${tone || ""}`}>{value}</p>
{sub && <p className="text-xs text-text-muted mt-0.5">{sub}</p>}
</Card>
);
}
export default function PxpipeClient() {
const [status, setStatus] = useState(null);
const [health, setHealth] = useState(null);
const [stats, setStats] = useState(null);
const [logs, setLogs] = useState(null);
const [windowId, setWindowId] = useState("last7d");
const [loading, setLoading] = useState(true);
const refresh = useCallback(async () => {
setLoading(true);
try {
const [statusRes, statsRes, logsRes] = await Promise.all([
fetch("/api/pxpipe/status", { headers: { "Cache-Control": "no-store" } }),
fetch("/api/pxpipe/stats"),
fetch("/api/pxpipe/logs?limit=50"),
]);
setStatus(await statusRes.json());
setStats(await statsRes.json());
setLogs(await logsRes.json());
const healthRes = await fetch("/api/pxpipe/health", { method: "POST" });
setHealth(await healthRes.json());
} catch {
/* sections render placeholders */
} finally {
setLoading(false);
}
}, []);
useEffect(() => {
refresh();
}, [refresh]);
const w = stats?.windows?.[windowId];
const statusLabel = !status
? "—"
: !status.installed
? "Not installed"
: health?.healthy
? "Healthy"
: status.running
? "Running"
: "Stopped";
return (
<div className="space-y-6 p-6">
<div className="flex items-center justify-between flex-wrap gap-3">
<h2 className="text-lg font-semibold flex items-center gap-2">
<span className="material-symbols-outlined text-primary">image</span>
PXPIPE Dashboard
</h2>
<div className="flex items-center gap-2">
<a href="/dashboard/token-saver" className="text-xs text-primary underline hover:opacity-80">
Token Saver settings
</a>
<Button size="sm" variant="ghost" onClick={refresh} disabled={loading}>
{loading ? "Refreshing…" : "Refresh"}
</Button>
</div>
</div>
<div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-6 gap-3">
<SummaryCard
label="Status"
value={statusLabel}
tone={health?.healthy ? "text-success" : status?.installed ? "text-warning" : "text-text-muted"}
sub={status?.enabled ? "Enabled in pipeline" : "Disabled in pipeline"}
/>
<SummaryCard label="Version" value={status?.version ? `v${status.version}` : "—"} sub="pxpipe-proxy" />
<SummaryCard label="Uptime" value={fmtUptime(status?.uptimeMs)} sub="module loaded" />
<SummaryCard label="Requests" value={w ? w.requests.toLocaleString() : "—"} />
<SummaryCard label="Compressed" value={w ? w.compressed.toLocaleString() : "—"} tone="text-success" />
<SummaryCard label="Bypassed" value={w ? w.bypassed.toLocaleString() : "—"} />
</div>
<Card className="p-4">
<div className="flex items-center justify-between flex-wrap gap-3 mb-4">
<h3 className="font-medium">Token savings (estimated)</h3>
<div className="flex items-center gap-1 rounded-lg border border-border bg-bg-subtle p-1">
{WINDOW_TABS.map((tab) => (
<button
key={tab.id}
onClick={() => setWindowId(tab.id)}
className={`px-3 py-1 rounded-md text-xs font-medium transition-colors ${
windowId === tab.id
? "bg-primary text-white shadow-sm"
: "text-text-muted hover:text-text hover:bg-bg-hover"
}`}
>
{tab.label}
</button>
))}
</div>
</div>
<div className="grid grid-cols-2 md:grid-cols-4 gap-4 text-center">
<div>
<p className="text-xs text-text-muted">Original tokens</p>
<p className="text-lg font-semibold">{w ? fmtTokens(w.tokensBeforeEst) : "—"}</p>
</div>
<div>
<p className="text-xs text-text-muted">After PXPIPE</p>
<p className="text-lg font-semibold">{w ? fmtTokens(w.tokensAfterEst) : "—"}</p>
</div>
<div>
<p className="text-xs text-text-muted">Saved</p>
<p className="text-lg font-semibold text-success">{w ? fmtTokens(w.tokensSavedEst) : "—"}</p>
</div>
<div>
<p className="text-xs text-text-muted">Reduction</p>
<p className="text-lg font-semibold text-success">{w ? `${w.savedPct}%` : "—"}</p>
</div>
</div>
<p className="text-xs text-text-muted mt-3">
Estimates from body size before/after imaging; billed usage per request
(recorded on the Usage page) remains the ground truth. Images generated:{" "}
{w ? w.imagesGenerated.toLocaleString() : "—"} · avg compression time:{" "}
{w ? `${w.avgCompressionMs}ms` : "—"} · errors: {w ? w.errors : "—"}
</p>
</Card>
<Card className="p-4">
<h3 className="font-medium mb-3">Tokens saved last 30 days</h3>
{stats?.timeline?.some((d) => d.tokensSavedEst > 0) ? (
<ResponsiveContainer width="100%" height={220}>
<AreaChart data={stats.timeline} margin={{ top: 4, right: 8, left: 0, bottom: 0 }}>
<defs>
<linearGradient id="gradPxpipe" x1="0" y1="0" x2="0" y2="1">
<stop offset="5%" stopColor="#10b981" stopOpacity={0.25} />
<stop offset="95%" stopColor="#10b981" stopOpacity={0} />
</linearGradient>
</defs>
<CartesianGrid strokeDasharray="3 3" strokeOpacity={0.2} />
<XAxis dataKey="date" tick={{ fontSize: 11 }} tickFormatter={(d) => d.slice(5)} />
<YAxis tick={{ fontSize: 11 }} tickFormatter={fmtTokens} width={48} />
<Tooltip formatter={(v) => [fmtTokens(v), "Tokens saved"]} labelFormatter={(d) => d} />
<Area type="monotone" dataKey="tokensSavedEst" stroke="#10b981" fill="url(#gradPxpipe)" strokeWidth={2} />
</AreaChart>
</ResponsiveContainer>
) : (
<div className="h-32 flex items-center justify-center text-text-muted text-sm">
No savings recorded yet enable PXPIPE in the Token Saver and route a large Claude-format request.
</div>
)}
</Card>
<Card className="p-4">
<h3 className="font-medium mb-3">History</h3>
<div className="overflow-x-auto">
<table className="w-full text-sm">
<thead>
<tr className="text-left text-xs text-text-muted border-b border-border">
<th className="py-2 pr-3">Time</th>
<th className="py-2 pr-3">Model</th>
<th className="py-2 pr-3 text-right">Original</th>
<th className="py-2 pr-3 text-right">Compressed</th>
<th className="py-2 pr-3 text-right">Saved</th>
<th className="py-2 pr-3 text-right">%</th>
<th className="py-2 pr-3 text-right">Duration</th>
<th className="py-2">Status</th>
</tr>
</thead>
<tbody>
{(stats?.recent || []).slice(0, 50).map((ev, i) => (
<tr key={`${ev.ts}-${i}`} className="border-b border-border/50">
<td className="py-1.5 pr-3 whitespace-nowrap text-text-muted">
{new Date(ev.ts).toLocaleString()}
</td>
<td className="py-1.5 pr-3 font-mono text-xs">{ev.provider ? `${ev.provider}/${ev.model}` : ev.model || "—"}</td>
<td className="py-1.5 pr-3 text-right font-mono text-xs">
{ev.applied ? fmtTokens(ev.tokensBeforeEst) : "—"}
</td>
<td className="py-1.5 pr-3 text-right font-mono text-xs">
{ev.applied ? fmtTokens(ev.tokensAfterEst) : "—"}
</td>
<td className="py-1.5 pr-3 text-right font-mono text-xs text-success">
{ev.applied ? fmtTokens(ev.tokensSavedEst) : "—"}
</td>
<td className="py-1.5 pr-3 text-right font-mono text-xs">
{ev.applied ? `${ev.savedPct}%` : "—"}
</td>
<td className="py-1.5 pr-3 text-right font-mono text-xs">
{ev.durationMs != null ? `${ev.durationMs}ms` : "—"}
</td>
<td className="py-1.5">
<span
className={`text-xs px-2 py-0.5 rounded ${
ev.applied
? "bg-success/15 text-success"
: ev.reason === "transform_error" || ev.reason === "timeout"
? "bg-danger/15 text-danger"
: "bg-warning/15 text-warning"
}`}
title={ev.detail || ""}
>
{ev.applied ? "Compressed" : REASON_LABELS[ev.reason] || ev.reason}
</span>
</td>
</tr>
))}
{(!stats?.recent || stats.recent.length === 0) && (
<tr>
<td colSpan={8} className="py-6 text-center text-text-muted text-sm">
No PXPIPE activity yet
</td>
</tr>
)}
</tbody>
</table>
</div>
</Card>
<Card className="p-4" id="logs">
<h3 className="font-medium mb-3">PXPIPE Logs</h3>
{logs?.installLog ? (
<pre className="rounded bg-black/5 dark:bg-white/5 p-3 text-xs font-mono overflow-x-auto max-h-64 overflow-y-auto whitespace-pre-wrap">
{logs.installLog}
</pre>
) : (
<p className="text-sm text-text-muted">No install log yet.</p>
)}
</Card>
</div>
);
}
@@ -0,0 +1,5 @@
import PxpipeClient from "./PxpipeClient";
export default function PxpipePage() {
return <PxpipeClient />;
}
@@ -37,6 +37,19 @@ export default function TokenSaverClient() {
const [cavemanLevel, setCavemanLevel] = useState("full");
const [ponytailEnabled, setPonytailEnabled] = useState(false);
const [ponytailLevel, setPonytailLevel] = useState("full");
const [pxpipeEnabled, setPxpipeEnabled] = useState(false);
const [pxpipeMinChars, setPxpipeMinChars] = useState(25000);
const [pxpipeStatus, setPxpipeStatus] = useState({
installed: false,
installing: false,
running: false,
version: null,
loading: true,
});
const [pxpipeHealth, setPxpipeHealth] = useState(null);
const [showPxpipeModal, setShowPxpipeModal] = useState(false);
const [pxpipeActionLoading, setPxpipeActionLoading] = useState(false);
const [pxpipeActionError, setPxpipeActionError] = useState("");
const [locale, setLocale] = useState("en");
const { copied, copy } = useCopyToClipboard();
@@ -232,6 +245,59 @@ export default function TokenSaverClient() {
patchSetting({ ponytailLevel: level });
};
const refreshPxpipeStatus = useCallback(async () => {
setPxpipeStatus((s) => ({ ...s, loading: true }));
try {
const res = await fetch("/api/pxpipe/status", {
headers: { "Cache-Control": "no-store" },
});
const data = await res.json();
setPxpipeStatus({ ...data, loading: false });
if (typeof data.minChars === "number") setPxpipeMinChars(data.minChars);
} catch {
setPxpipeStatus({ installed: false, installing: false, running: false, version: null, loading: false });
}
}, []);
const runPxpipeHealth = useCallback(async () => {
try {
const res = await fetch("/api/pxpipe/health", { method: "POST" });
setPxpipeHealth(await res.json());
} catch (e) {
setPxpipeHealth({ healthy: false, checks: [], error: e.message });
}
}, []);
const pxpipeAction = useCallback(
async (endpoint) => {
setPxpipeActionError("");
setPxpipeActionLoading(true);
try {
const res = await fetch(`/api/pxpipe/${endpoint}`, { method: "POST" });
const data = await res.json().catch(() => ({}));
if (!res.ok) throw new Error(data.error || `PXPIPE ${endpoint} failed`);
await refreshPxpipeStatus();
await runPxpipeHealth();
} catch (e) {
setPxpipeActionError(e.message);
} finally {
setPxpipeActionLoading(false);
}
},
[refreshPxpipeStatus, runPxpipeHealth]
);
const handlePxpipeEnabled = (value) => {
setPxpipeEnabled(value);
patchSetting({ pxpipeEnabled: value });
};
const handlePxpipeMinCharsBlur = () => {
const next = Math.max(0, Number(pxpipeMinChars) || 25000);
setPxpipeMinChars(next);
patchSetting({ pxpipeMinChars: next });
};
useEffect(() => {
const loadSettings = async () => {
try {
@@ -245,12 +311,16 @@ export default function TokenSaverClient() {
setCavemanLevel(data.cavemanLevel || "full");
setPonytailEnabled(!!data.ponytailEnabled);
setPonytailLevel(data.ponytailLevel || "full");
setPxpipeEnabled(!!data.pxpipeEnabled);
if (typeof data.pxpipeMinChars === "number") setPxpipeMinChars(data.pxpipeMinChars);
refreshHeadroomStatus();
// PRD: run the PXPIPE health check automatically when the page opens
refreshPxpipeStatus().then(runPxpipeHealth);
}
} catch {}
};
loadSettings();
}, [refreshHeadroomStatus]);
}, [refreshHeadroomStatus, refreshPxpipeStatus, runPxpipeHealth]);
const headroomRunning = !!headroomStatus.running;
const headroomStatusLabel = headroomStatus.loading
@@ -267,6 +337,23 @@ export default function TokenSaverClient() {
const headroomManaged =
headroomLocalUrl && !!headroomStatus.managedPid;
const pxpipeHealthy = pxpipeHealth?.healthy === true;
const pxpipeStatusLabel = pxpipeStatus.loading
? "Checking…"
: pxpipeStatus.installing
? "Installing…"
: !pxpipeStatus.installed
? "Not installed"
: pxpipeHealthy
? "Healthy"
: pxpipeStatus.running
? "Running"
: "Stopped";
const pxpipeChipClass =
pxpipeHealthy || pxpipeStatus.running
? "bg-success/15 text-success"
: "bg-warning/15 text-warning";
return (
<div className="space-y-6 p-6">
<Card id="rtk">
@@ -502,6 +589,49 @@ export default function TokenSaverClient() {
/>
</div>
</div>
<div className="flex items-center justify-between pt-4 mt-4 border-t border-border gap-4 flex-wrap">
<div className="min-w-0 flex-1">
<div className="flex items-center gap-3 flex-wrap">
<p className="font-medium">
Compress prompts as images{" "}
<a
href="https://github.com/teamchong/pxpipe"
target="_blank"
rel="noreferrer"
className="text-xs font-normal text-primary underline hover:opacity-80"
>
(PXPIPE)
</a>
</p>
<span className={`text-xs px-2 py-0.5 rounded ${pxpipeChipClass}`}>
{pxpipeStatusLabel}
</span>
<button
type="button"
onClick={() => setShowPxpipeModal(true)}
className="text-xs text-primary underline hover:opacity-80"
>
{pxpipeStatus.installed ? "Manage" : "Setup"}
</button>
<a
href="/dashboard/pxpipe"
className="text-xs text-primary underline hover:opacity-80"
>
Dashboard
</a>
</div>
<p className="text-sm text-text-muted mt-1">
Transforms large textual context into optimized images before
sending to the LLM. Ideal for huge prompts, tool outputs and long
conversations.
</p>
</div>
<Toggle
checked={pxpipeEnabled}
disabled={!pxpipeStatus.installed}
onChange={() => handlePxpipeEnabled(!pxpipeEnabled)}
/>
</div>
</Card>
<Modal
@@ -611,6 +741,114 @@ export default function TokenSaverClient() {
</div>
</div>
</Modal>
<Modal
isOpen={showPxpipeModal}
title={pxpipeStatus.installed ? "PXPIPE" : "Setup PXPIPE"}
onClose={() => setShowPxpipeModal(false)}
>
<div className="flex flex-col gap-4">
<p className="text-sm text-text-muted">
Compress prompts using multimodal encoding. Runs in-process no
extra server or environment variables required.
</p>
<div className="flex items-center justify-between text-sm">
<span>Status</span>
<span className={pxpipeHealthy || pxpipeStatus.running ? "text-success" : "text-warning"}>
{pxpipeStatusLabel}
{pxpipeStatus.version ? ` · v${pxpipeStatus.version}` : ""}
</span>
</div>
{pxpipeHealth?.checks?.length > 0 && (
<div className="flex flex-col gap-1 rounded border border-border p-3">
<p className="text-sm font-medium mb-1">Health check</p>
{pxpipeHealth.checks.map((check) => (
<div key={check.id} className="flex items-center justify-between text-xs">
<span className={check.ok ? "text-success" : "text-warning"}>
{check.ok ? "●" : "○"} {check.label}
</span>
{check.detail && (
<span className="text-text-muted font-mono truncate max-w-[50%]">{check.detail}</span>
)}
</div>
))}
{pxpipeHealth.error && (
<p className="text-xs text-warning mt-1">{pxpipeHealth.error}</p>
)}
</div>
)}
{!pxpipeStatus.installed ? (
<div className="flex flex-col gap-2">
<p className="text-sm text-warning">PXPIPE is not installed.</p>
<Button
onClick={() => pxpipeAction("install")}
fullWidth
disabled={pxpipeActionLoading || pxpipeStatus.installing}
>
{pxpipeActionLoading || pxpipeStatus.installing ? "Installing…" : "Install"}
</Button>
<p className="text-xs text-text-muted">
Installs the npm package <code className="font-mono">pxpipe-proxy</code> into
the 9Router data directory. May take a few minutes.
</p>
</div>
) : (
<div className="grid grid-cols-2 gap-2">
{pxpipeStatus.running ? (
<>
<Button onClick={() => pxpipeAction("restart")} variant="ghost" disabled={pxpipeActionLoading}>
Restart
</Button>
<Button onClick={() => pxpipeAction("stop")} variant="ghost" disabled={pxpipeActionLoading}>
Stop
</Button>
</>
) : (
<Button onClick={() => pxpipeAction("start")} disabled={pxpipeActionLoading}>
{pxpipeActionLoading ? "Starting…" : "Start"}
</Button>
)}
<Button onClick={() => pxpipeAction("install")} variant="ghost" disabled={pxpipeActionLoading}>
Repair
</Button>
<a
href="/dashboard/pxpipe#logs"
className="col-span-2 rounded border border-border px-4 py-2 text-center text-sm hover:bg-surface-2"
>
Open Logs
</a>
</div>
)}
<div className="flex flex-col gap-1">
<p className="text-sm font-medium">Minimum prompt size (chars)</p>
<Input
value={String(pxpipeMinChars)}
onChange={(e) => setPxpipeMinChars(e.target.value)}
onBlur={handlePxpipeMinCharsBlur}
placeholder="25000"
className="font-mono text-sm"
/>
<p className="text-xs text-text-muted">
Requests smaller than this bypass PXPIPE and are sent as-is.
</p>
</div>
{pxpipeActionError && (
<p className="text-sm text-warning">{pxpipeActionError}</p>
)}
<div className="flex gap-2">
<Button
onClick={() => refreshPxpipeStatus().then(runPxpipeHealth)}
variant="ghost"
fullWidth
>
Recheck
</Button>
<Button onClick={() => setShowPxpipeModal(false)} fullWidth>
Done
</Button>
</div>
</div>
</Modal>
</div>
);
}
@@ -412,7 +412,49 @@ export default function RequestDetailsTab() {
</span>
</div>
</div>
{selectedDetail.pxpipe && (
<div className="rounded-lg border border-black/5 dark:border-white/5 p-4">
<div className="flex items-center gap-2 mb-2">
<span className="material-symbols-outlined text-[18px] text-text-muted">image</span>
<span className="font-semibold text-sm text-text-main">PXPIPE</span>
<span className={cn(
"text-xs px-2 py-0.5 rounded",
selectedDetail.pxpipe.applied
? "bg-green-500/15 text-green-600"
: "bg-amber-500/15 text-amber-600"
)}>
{selectedDetail.pxpipe.applied ? "Activated" : "Skipped"}
</span>
</div>
{selectedDetail.pxpipe.applied ? (
<div className="grid grid-cols-2 gap-2 text-sm sm:grid-cols-4">
<div>
<span className="text-text-muted block text-xs">Original (est.)</span>
<span className="font-mono">{(selectedDetail.pxpipe.tokensBeforeEst || 0).toLocaleString()} tokens</span>
</div>
<div>
<span className="text-text-muted block text-xs">Compressed (est.)</span>
<span className="font-mono">{(selectedDetail.pxpipe.tokensAfterEst || 0).toLocaleString()} tokens</span>
</div>
<div>
<span className="text-text-muted block text-xs">Saved</span>
<span className="font-mono text-green-600">{selectedDetail.pxpipe.savedPct || 0}%</span>
</div>
<div>
<span className="text-text-muted block text-xs">Images</span>
<span className="font-mono">{selectedDetail.pxpipe.imageCount || 0} ({selectedDetail.pxpipe.durationMs || 0}ms)</span>
</div>
</div>
) : (
<p className="text-sm text-text-muted">
Reason: <span className="font-mono">{selectedDetail.pxpipe.reason}</span>
{selectedDetail.pxpipe.detail ? `${selectedDetail.pxpipe.detail}` : ""}
</p>
)}
</div>
)}
<div className="space-y-4">
<CollapsibleSection title="1. Client Request (Input)" defaultOpen={true} icon="input">
<pre className="max-h-[300px] max-w-full overflow-auto rounded-lg border border-black/5 bg-black/5 p-3 font-mono text-xs text-text-main dark:border-white/5 dark:bg-white/5 sm:p-4">