fix(container): persist npm cache for per-task MCP servers

Ephemeral task containers re-resolve and re-download npx-launched MCP
server packages from the npm registry on every task, since each task
gets a fresh container with no persistent cache -- a worse amplifier
of a registry outage than the daemon-restart case d4bb914b already
fixed.

Extract the daemon's npm-cache env logic into mcp.NpmCacheEnv, shared
by both the daemon's own long-lived npx MCP servers and archie-agent's
per-task ones. Mount a new archie-cache-mcp-npm Docker volume at
/data/cache/mcp-npm on every task container regardless of ecosystem
(MCP servers are daemon-wide config, not tied to the task repo's
language), and point npx-launched per-task stdio transports at it.

Closes archie-core-qk8m.
This commit is contained in:
sam committed 2026-08-22 21:13:33 +10:00
1 parent 943da54bdd
commit 99738845b6
7 files changed
+246 -37

No files matched your search

+6 -19
View File
@@ -180,20 +180,10 @@ func (a chatTaskListerAdapter) ListChatTasks(ctx context.Context, identity strin
// restarts, instead of npm re-resolving and re-downloading the package
// from the registry every time the daemon starts. Rooted under the
// daemon's own work dir so it persists regardless of whether the daemon
// itself runs in an ephemeral container. Empty for any command other than
// npx, which has no such registry dependency to begin with.
//
// This covers the npm package itself, not a package's own separate
// download path -- e.g. Playwright/Puppeteer-based servers fetch browser
// binaries from a CDN via a postinstall script, gated by their own env
// vars, which this does not touch.
//
// Matched by base name, not exact string: this repo's own
// config.example.toml uses absolute paths for other daemon-launched
// commands (update_check_command, update_install_command), so an operator
// who pins npx the same way ("/usr/local/bin/npx") must still get the
// fix -- an exact match would skip it silently, with no error logged,
// leaving the original bug in place unnoticed.
// itself runs in an ephemeral container. See mcp.NpmCacheEnv for the
// command-matching and env var details shared with archie-agent's
// per-task equivalent (internal/app/agentworker/mcp_providers.go), which
// points at a mounted cache volume instead of a work-dir subdirectory.
//
// workDir is unconditionally defaulted before registerTools runs
// (internal/infrastructure/configuration's applyGeneralDefaults), but
@@ -202,13 +192,10 @@ func (a chatTaskListerAdapter) ListChatTasks(ctx context.Context, identity strin
// persistent data directory -- guard it explicitly rather than trust that
// invariant here too, the way memoryProvider already does nearby.
func npmCacheServerEnv(command, workDir string) []string {
if filepath.Base(command) != "npx" || workDir == "" {
if workDir == "" {
return nil
}
return []string{
"NPM_CONFIG_CACHE=" + filepath.Join(workDir, "mcp-npm-cache"),
"NPM_CONFIG_PREFER_OFFLINE=true",
}
return mcp.NpmCacheEnv(command, filepath.Join(workDir, "mcp-npm-cache"))
}
func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovider.Engine, error) {
@@ -8,6 +8,7 @@ import (
"strings"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/storage"
"github.com/samcharles93/archie-core/internal/tools"
"github.com/samcharles93/archie-core/internal/tools/mcp"
toolprovider "github.com/samcharles93/archie-core/internal/tools/provider"
@@ -102,9 +103,17 @@ func mcpTransportForServer(
if command == "" {
return nil, fmt.Errorf("MCP stdio server %q requires a command", name)
}
// storage.MCPNPMCacheMountDir is a shared Docker volume mounted on
// every task container (internal/storage's alwaysOnCacheVolumes),
// so an npx-launched MCP server reuses a warm npm cache across
// tasks instead of re-resolving/re-downloading from the registry
// in each fresh ephemeral container. Mirrors the daemon's own
// npx MCP servers (cmd/archied/main.go's npmCacheServerEnv),
// which persists across daemon restarts the same way.
return mcp.NewStdioTransport(mcp.StdioTransportConfig{
Command: command,
Args: append([]string(nil), server.Args...),
Env: mcp.NpmCacheEnv(command, storage.MCPNPMCacheMountDir),
}), nil
case "http", "streamablehttp":
url := strings.TrimSpace(server.URL)
+42 -1
View File
@@ -10,6 +10,7 @@ import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/plugin"
"github.com/samcharles93/archie-core/internal/storage"
"github.com/samcharles93/archie-core/internal/tools"
protocolmcp "github.com/samcharles93/archie-core/internal/tools/mcp"
toolprovider "github.com/samcharles93/archie-core/internal/tools/provider"
@@ -72,6 +73,7 @@ func TestBuildMCPProviderSelectsTransport(t *testing.T) {
wantType any
wantCommand string
wantArgs []string
wantEnv []string
wantEndpoint string
wantMessageEndpoint string
wantHeaders map[string]string
@@ -93,6 +95,29 @@ func TestBuildMCPProviderSelectsTransport(t *testing.T) {
wantType: (*protocolmcp.StdioTransport)(nil),
wantCommand: "server",
},
{
// Task containers are ephemeral, so an npx-launched MCP server
// must be pointed at the shared mcp-npm cache volume mounted on
// every container -- otherwise it re-resolves/re-downloads from
// the registry on every single task.
name: "npx stdio server gets the persistent npm cache",
server: config.MCPServer{Name: "local", Command: "npx", Args: []string{"-y", "some-mcp-server"}},
wantTransport: "stdio",
wantType: (*protocolmcp.StdioTransport)(nil),
wantCommand: "npx",
wantArgs: []string{"-y", "some-mcp-server"},
wantEnv: []string{
"NPM_CONFIG_CACHE=" + storage.MCPNPMCacheMountDir,
"NPM_CONFIG_PREFER_OFFLINE=true",
},
},
{
name: "non-npx stdio server gets no npm cache env",
server: config.MCPServer{Name: "local", Command: "/usr/local/bin/my-mcp-server"},
wantTransport: "stdio",
wantType: (*protocolmcp.StdioTransport)(nil),
wantCommand: "/usr/local/bin/my-mcp-server",
},
{
name: "http",
server: config.MCPServer{Name: "remote", Transport: "http", URL: " https://example.test/mcp ", Headers: map[string]string{"Authorization": "Bearer test"}},
@@ -175,7 +200,7 @@ func TestBuildMCPProviderSelectsTransport(t *testing.T) {
if got, want := transport.Elem().Type(), reflect.TypeOf(tc.wantType); got != want {
t.Fatalf("transport type = %v, want %v", got, want)
}
assertMCPTransportConfig(t, transport.Elem(), tc.wantCommand, tc.wantArgs, tc.wantEndpoint, tc.wantMessageEndpoint, tc.wantHeaders)
assertMCPTransportConfig(t, transport.Elem(), tc.wantCommand, tc.wantArgs, tc.wantEnv, tc.wantEndpoint, tc.wantMessageEndpoint, tc.wantHeaders)
})
}
}
@@ -185,6 +210,7 @@ func assertMCPTransportConfig(
transport reflect.Value,
wantCommand string,
wantArgs []string,
wantEnv []string,
wantEndpoint string,
wantMessageEndpoint string,
wantHeaders map[string]string,
@@ -228,6 +254,21 @@ func assertMCPTransportConfig(
}
}
}
// Env only exists on StdioTransportConfig; other transports have no
// registry-fetch dependency for this check to apply to.
if envField := config.FieldByName("Env"); envField.Kind() != reflect.Invalid {
got := make([]string, envField.Len())
for i := range envField.Len() {
got[i] = envField.Index(i).String()
}
if len(got) == 0 {
got = nil
}
if !reflect.DeepEqual(got, wantEnv) {
t.Errorf("transport config Env = %v, want %v", got, wantEnv)
}
}
}
func TestStartMCPProviderLifecycle(t *testing.T) {
+34 -10
View File
@@ -21,6 +21,9 @@
// bun/ -- Bun package cache (shared)
// pip/ -- pip cache (shared)
// cargo/ -- Rust cargo cache (shared)
// mcp-npm/ -- npm cache for npx-launched per-task MCP
// servers (shared, mounted regardless of the
// task repo's ecosystem -- see MCPNPMCacheMountDir)
//
// Cache volumes are named Docker volumes created once and shared across all
// tasks. They are never deleted -- the daemon operator manages them.
@@ -134,6 +137,15 @@ const (
PluginsDir = PersistentMountDir + "/plugins"
)
// MCPNPMCacheMountDir is the fixed container path where the npm package
// cache for npx-launched per-task MCP servers is mounted. Unlike the
// ecosystem caches below, this is mounted on every task container
// regardless of the task repo's language: per-task MCP servers come from
// daemon-wide config (config.MCPServer), not from anything specific to the
// checked-out repo, so an npx-based server needs the cache warm whether the
// task is a Go repo, a Python repo, or anything else.
const MCPNPMCacheMountDir = "/data/cache/mcp-npm"
// Backend prepares container storage. Each container runtime backend
// (Docker, future containerd, etc.) implements this interface.
type Backend interface {
@@ -155,6 +167,16 @@ type cacheVolume struct {
MountPath string // container destination path
}
// alwaysOnCacheVolumes are shared cache volumes mounted on every task
// container regardless of the task repo's ecosystem, because what they
// cache isn't tied to the repo being worked on. The npx package cache for
// per-task MCP servers is the only current instance: MCP servers are
// daemon-wide config, not per-repo, so an npx-based one needs a warm cache
// no matter which repo the task happens to be against.
var alwaysOnCacheVolumes = []cacheVolume{
{Name: "archie-cache-mcp-npm", MountPath: MCPNPMCacheMountDir},
}
// cacheVolumesByEcosystem maps ecosystem names to their shared cache volumes.
// Volumes are created once by the pool and never deleted.
var cacheVolumesByEcosystem = map[string][]cacheVolume{
@@ -183,14 +205,15 @@ var cacheVolumesByEcosystem = map[string][]cacheVolume{
},
}
// cacheMounts returns the cache mount specs for an ecosystem, sorted by
// destination path for deterministic container configuration.
// Ecosystem is case-insensitive -- "Python" and "python" are equivalent.
// cacheMounts returns the cache mount specs for an ecosystem -- the
// always-on volumes plus any matched by ecosystem -- sorted by destination
// path for deterministic container configuration. Ecosystem is
// case-insensitive -- "Python" and "python" are equivalent. An unknown or
// empty ecosystem still returns the always-on volumes.
func cacheMounts(ecosystem string) []Mount {
vols, ok := cacheVolumesByEcosystem[strings.ToLower(ecosystem)]
if !ok {
return nil
}
vols := append([]cacheVolume(nil), alwaysOnCacheVolumes...)
vols = append(vols, cacheVolumesByEcosystem[strings.ToLower(ecosystem)]...)
mounts := make([]Mount, len(vols))
for i, v := range vols {
mounts[i] = Mount{
@@ -279,9 +302,10 @@ func repoVolumeName(owner, repo string) string {
}
// Setup returns the mount list for a task container. Mounts are ordered:
// 1. /data/worktree bind mount (always first)
// 2. /data/repo volume mount (only when PersistentStorage is true)
// 3. /data/cache/<ecosystem> volume mounts (sorted by destination)
// 1. /data/worktree bind mount (always first)
// 2. /data/repo volume mount (only when PersistentStorage is true)
// 3. cache volume mounts: the always-on volumes plus /data/cache/<ecosystem>
// (sorted together by destination)
func (d *DockerBackend) Setup(ctx context.Context, task TaskRef) ([]Mount, error) {
mounts := []Mount{
{
+66 -7
View File
@@ -88,10 +88,27 @@ func TestMountListForEcosystemRust(t *testing.T) {
}
}
func TestMountListUnknownEcosystemReturnsBaseOnly(t *testing.T) {
func TestMountListUnknownEcosystemReturnsAlwaysOnOnly(t *testing.T) {
mounts := cacheMounts("custom")
if len(mounts) != 0 {
t.Errorf("custom ecosystem returned %d mounts, want 0", len(mounts))
names := mountDestinations(mounts)
if !contains(names, MCPNPMCacheMountDir) {
t.Errorf("unknown ecosystem missing always-on mcp-npm cache in %v", names)
}
if len(mounts) != len(alwaysOnCacheVolumes) {
t.Errorf("custom ecosystem returned %d mounts, want %d (always-on only)", len(mounts), len(alwaysOnCacheVolumes))
}
}
func TestMountListAlwaysIncludesMCPNPMCache(t *testing.T) {
// The npm cache for per-task MCP servers isn't tied to the task repo's
// ecosystem, so it must be present regardless of which ecosystem (or
// none) is requested.
for _, eco := range []string{"go", "node", "python", "rust", "custom", ""} {
mounts := cacheMounts(eco)
names := mountDestinations(mounts)
if !contains(names, MCPNPMCacheMountDir) {
t.Errorf("ecosystem %q missing always-on mcp-npm cache in %v", eco, names)
}
}
}
@@ -183,6 +200,42 @@ func TestDockerBackendSetupIncludesCacheMounts(t *testing.T) {
}
}
func TestDockerBackendSetupIncludesMCPNPMCacheRegardlessOfEcosystem(t *testing.T) {
// The npx package cache for per-task MCP servers must be mounted on
// every task container, not just ones matching an ecosystem with its
// own cache volumes: MCP servers are daemon-wide config, unrelated to
// the repo the task happens to run against.
dir := t.TempDir()
if err := os.MkdirAll(dir, 0o755); err != nil {
t.Fatal(err)
}
backend := &DockerBackend{}
mounts, err := backend.Setup(context.Background(), TaskRef{
WorktreeDir: dir,
Ecosystem: "rust",
})
if err != nil {
t.Fatal(err)
}
found := false
for _, m := range mounts {
if m.Destination == MCPNPMCacheMountDir {
found = true
if m.Type != MountTypeVolume {
t.Errorf("mcp-npm cache mount type = %q, want volume", m.Type)
}
if m.Source != "archie-cache-mcp-npm" {
t.Errorf("mcp-npm cache mount source = %q, want archie-cache-mcp-npm", m.Source)
}
}
}
if !found {
t.Error("Setup did not include the mcp-npm cache mount")
}
}
func TestDockerBackendSetupWorktreeMountIsFirst(t *testing.T) {
// Worktree bind mount must be the first entry -- container create
// depends on this order for overlay semantics.
@@ -266,7 +319,8 @@ func TestDockerBackendSetupEmptyEcosystem(t *testing.T) {
}
func TestDockerBackendSetupUnknownEcosystemSkipped(t *testing.T) {
// Unknown ecosystem must not add cache mounts, but must not error.
// Unknown ecosystem must not add ecosystem-specific cache mounts (only
// the always-on ones), but must not error.
dir := t.TempDir()
if err := os.MkdirAll(dir, 0o755); err != nil {
t.Fatal(err)
@@ -281,7 +335,7 @@ func TestDockerBackendSetupUnknownEcosystemSkipped(t *testing.T) {
t.Fatal("Setup errored on unknown ecosystem:", err)
}
for _, m := range mounts {
if m.Destination != "/data/worktree" {
if m.Destination != "/data/worktree" && m.Destination != MCPNPMCacheMountDir {
t.Errorf("unexpected mount %s for unknown ecosystem", m.Destination)
}
}
@@ -437,7 +491,11 @@ func TestRepoVolumeName(t *testing.T) {
}
func TestDockerBackendLabelsPersistentRepoVolumes(t *testing.T) {
var createBody string
// Setup also ensures the always-on mcp-npm cache volume (and any
// ecosystem-specific ones) alongside the per-repo volume, so every
// /volumes/create body must be collected rather than captured into a
// single variable that the last request would overwrite.
var createBodies []string
cli := dockerTestClient(t, func(req *http.Request) (*http.Response, error) {
path := dockerAPIPath(req.URL.Path)
switch {
@@ -448,7 +506,7 @@ func TestDockerBackendLabelsPersistentRepoVolumes(t *testing.T) {
if readErr != nil {
return nil, readErr
}
createBody = string(data)
createBodies = append(createBodies, string(data))
return dockerResponse(http.StatusCreated, `{"Name":"archie-repo-alice-demo","Driver":"local","Labels":{}}`), nil
default:
return dockerResponse(http.StatusNotFound, `{"message":"unexpected request"}`), nil
@@ -465,6 +523,7 @@ func TestDockerBackendLabelsPersistentRepoVolumes(t *testing.T) {
}); err != nil {
t.Fatal(err)
}
createBody := strings.Join(createBodies, "\n")
if !strings.Contains(createBody, `"com.samcharles93.archie.storage":"repo"`) {
t.Fatalf("persistent volume create body lacks Archie repo label: %s", createBody)
}
+29
View File
@@ -0,0 +1,29 @@
package mcp
import "path/filepath"
// NpmCacheEnv returns environment variables that make an npx-launched MCP
// server reuse a persistent package cache at cacheDir, instead of npm
// re-resolving and re-downloading the package from the registry on every
// launch. Empty for any command other than npx, or an empty cacheDir --
// npx has a registry dependency other commands don't, and an empty cacheDir
// means the caller has no persistent location to point npm at.
//
// This covers the npm package itself, not a package's own separate
// download path -- e.g. Playwright/Puppeteer-based servers fetch browser
// binaries from a CDN via a postinstall script, gated by their own env
// vars, which this does not touch.
//
// Matched by base name, not exact string: a command may be pinned via an
// absolute path (an operator's daemon config, or a container image's PATH),
// and an exact "npx" match would skip the fix silently, with no error
// logged, leaving the underlying registry re-fetch in place unnoticed.
func NpmCacheEnv(command, cacheDir string) []string {
if filepath.Base(command) != "npx" || cacheDir == "" {
return nil
}
return []string{
"NPM_CONFIG_CACHE=" + cacheDir,
"NPM_CONFIG_PREFER_OFFLINE=true",
}
}
+60
View File
@@ -0,0 +1,60 @@
package mcp
import (
"slices"
"testing"
)
func TestNpmCacheEnv(t *testing.T) {
cases := []struct {
name string
command string
cacheDir string
want []string
}{
{
name: "npx gets a persistent cache",
command: "npx",
cacheDir: "/data/cache/mcp-npm",
want: []string{
"NPM_CONFIG_CACHE=/data/cache/mcp-npm",
"NPM_CONFIG_PREFER_OFFLINE=true",
},
},
{
name: "an absolute path to npx still gets the persistent cache",
command: "/usr/local/bin/npx",
cacheDir: "/data/cache/mcp-npm",
want: []string{
"NPM_CONFIG_CACHE=/data/cache/mcp-npm",
"NPM_CONFIG_PREFER_OFFLINE=true",
},
},
{
name: "a non-npx command has no npm registry dependency to fix",
command: "/usr/local/bin/my-mcp-server",
cacheDir: "/data/cache/mcp-npm",
want: nil,
},
{
name: "empty command is left alone",
command: "",
cacheDir: "/data/cache/mcp-npm",
want: nil,
},
{
name: "empty cacheDir is refused rather than caching into the process CWD",
command: "npx",
cacheDir: "",
want: nil,
},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
got := NpmCacheEnv(c.command, c.cacheDir)
if !slices.Equal(got, c.want) {
t.Errorf("NpmCacheEnv(%q, %q) = %v, want %v", c.command, c.cacheDir, got, c.want)
}
})
}
}