Drive coding agents over the Agent Client Protocol

.naming-allowlist

@@ -21,3 +21,5 @@ keyring(bcq
 legacy bcq
 # RELEASING.md — actual GitHub App name
 bcq-release-bot
+# npm integrity hashes are base64 and can contain any letters
+./internal/connector/driver/acp/adapters/package-lock.json

.surface

@@ -5345,6 +5345,7 @@ FLAG basecamp config untrust --styled type=bool
 FLAG basecamp config untrust --todolist type=string
 FLAG basecamp config untrust --verbose type=count
 FLAG basecamp connect --account type=string
+FLAG basecamp connect --acp-adapters type=string
 FLAG basecamp connect --agent type=bool
 FLAG basecamp connect --cache-dir type=string
 FLAG basecamp connect --count type=bool

Makefile

@@ -130,6 +130,33 @@ qa-report:
 		echo ""; \
 	fi
 
+# The connector's acp driver runs pinned ACP adapters, installed here once by
+# an operator and never downloaded at dispatch time.
+# Where basecamp connect looks by default: an absolute $XDG_DATA_HOME, else
+# ~/.local/share (a relative XDG_DATA_HOME is ignored there too).
+ACP_ADAPTERS_DIR ?= $(if $(filter /%,$(XDG_DATA_HOME)),$(XDG_DATA_HOME),$(HOME)/.local/share)/basecamp/acp-adapters
+
+# Install the pinned ACP adapters (internal/connector/driver/acp/adapters).
+# --engine-strict: an adapter whose Node version requirement this machine does
+# not meet fails the install, not the first dispatch.
+.PHONY: acp-adapters
+acp-adapters:
+	@mkdir -p "$(ACP_ADAPTERS_DIR)"
+	cp internal/connector/driver/acp/adapters/package.json internal/connector/driver/acp/adapters/package-lock.json "$(ACP_ADAPTERS_DIR)/"
+	npm ci --prefix "$(ACP_ADAPTERS_DIR)" --ignore-scripts --no-audit --no-fund --engine-strict
+
+# The ACP adapter-compatibility test: eight checks through the acp driver
+# against each installed adapter (the spike's four, the worker shell's
+# environment, a decoy MCP server in the working directory, the task
+# token's bridge, and what an adapter does when a session's MCP server dies
+# mid-session). Sends real prompts (model quota); skipped
+# for an adapter that is not installed. ACP_TRANSCRIPTS=<dir> keeps redacted
+# JSON-RPC transcripts.
+.PHONY: test-acp-compat
+test-acp-compat: check-toolchain
+	BASECAMP_ACP_ADAPTERS_DIR="$(ACP_ADAPTERS_DIR)" BASECAMP_ACP_TRANSCRIPTS="$(ACP_TRANSCRIPTS)" \
+		$(GOTEST) -tags acpcompat -run TestAdapterCompat -count=1 -timeout 30m -v ./internal/connector/driver/acp/
+
 # Run tests with race detector
 .PHONY: race-test
 race-test: check-toolchain
@@ -294,6 +321,9 @@ provenance-check:
 .PHONY: vet
 vet: check-toolchain
 	$(GOVET) $(BUILD_TAGS) ./...
+	@# The adapter-compatibility test builds only with its own tag, so
+	@# nothing else would notice it rotting.
+	$(GOVET) -tags acpcompat ./internal/connector/driver/acp/
 
 # Format code
 .PHONY: fmt

internal/commands/connect_run.go

@@ -25,6 +25,7 @@ import (
 	"github.com/basecamp/basecamp-cli/internal/connector"
 	"github.com/basecamp/basecamp-cli/internal/connector/admission"
 	"github.com/basecamp/basecamp-cli/internal/connector/driver"
+	"github.com/basecamp/basecamp-cli/internal/connector/driver/acp"
 	"github.com/basecamp/basecamp-cli/internal/connector/driver/spawn"
 	"github.com/basecamp/basecamp-cli/internal/connector/ndjson"
 	"github.com/basecamp/basecamp-cli/internal/connector/setup"
@@ -38,6 +39,7 @@ type connectRunFlags struct {
 	shadow   bool
 	since    int64
 	driver   string
+	adapters string
 }
 
 func addConnectRunFlags(cmd *cobra.Command, f *connectRunFlags) {
@@ -47,7 +49,8 @@ func addConnectRunFlags(cmd *cobra.Command, f *connectRunFlags) {
 	fl.Var((*repeatedString)(&f.projects), "project", "Only hear events in this project id (repeatable; default every project the agent can see)")
 	fl.BoolVar(&f.shadow, "shadow", false, "Admit and log in an isolated state directory; dispatch and post nothing")
 	fl.Int64Var(&f.since, "since", 0, "Enter the feed just after this event id, whatever the ledger holds")
-	fl.StringVar(&f.driver, "driver", "", "Override connect.json's driver (spawn)")
+	fl.StringVar(&f.driver, "driver", "", "Override connect.json's driver (spawn or acp)")
+	fl.StringVar(&f.adapters, "acp-adapters", "", "Where the pinned ACP adapters are installed, for --driver acp (default $XDG_DATA_HOME/basecamp/acp-adapters)")
 }
 
 // connectStateHome is the directory holding the connector's state root, from
@@ -123,6 +126,23 @@ func connectSessionsPath(file setup.File) string {
 	return filepath.Join(base, "bcc-"+connector.StateDirName(file.AccountID, file.Agent.PersonID))
 }
 
+// connectDriver is the driver connect.json (or --driver) names for its
+// worker. The acp driver runs the worker's pinned ACP adapter, found where it
+// was installed; nothing is downloaded here.
+func connectDriver(name, worker, adaptersDir string) (driver.Driver, error) {
+	if name != setup.DriverACP {
+		return spawn.New(worker, spawn.Options{})
+	}
+	if adaptersDir != "" && !filepath.IsAbs(adaptersDir) {
+		abs, err := filepath.Abs(adaptersDir)
+		if err != nil {
+			return nil, err
+		}
+		adaptersDir = abs
+	}
+	return acp.ForWorker(worker, adaptersDir, nil)
+}
+
 func runConnect(cmd *cobra.Command, f *connectRunFlags) error {
 	if !connectSupportedOS(runtime.GOOS) {
 		return output.ErrUsage("basecamp connect runs on macOS and Linux only: it ends a crashed connector's workers by process group and start time, which only those two can read")
@@ -165,8 +185,8 @@ func runConnect(cmd *cobra.Command, f *connectRunFlags) error {
 	if f.driver != "" {
 		driverName = f.driver
 	}
-	if !f.shadow && driverName != setup.DriverSpawn {
-		return output.ErrUsage(fmt.Sprintf("driver %q is not available yet; use %q", driverName, setup.DriverSpawn))
+	if !f.shadow && driverName != setup.DriverSpawn && driverName != setup.DriverACP {
+		return output.ErrUsage(fmt.Sprintf("driver %q is not %q or %q", driverName, setup.DriverSpawn, setup.DriverACP))
 	}
 
 	account, err := connectAccount(app, name)
@@ -270,7 +290,7 @@ func runConnect(cmd *cobra.Command, f *connectRunFlags) error {
 			return err
 		}
 		routes := newConnectRoutes(path, file, logger)
-		worker, err := spawn.New(file.WorkerName(), spawn.Options{})
+		worker, err := connectDriver(driverName, file.WorkerName(), f.adapters)
 		if err != nil {
 			return output.ErrUsage(err.Error())
 		}

internal/commands/connect_run_test.go

@@ -16,6 +16,7 @@ import (
 	"github.com/basecamp/basecamp-cli/internal/config"
 	"github.com/basecamp/basecamp-cli/internal/connector"
 	"github.com/basecamp/basecamp-cli/internal/connector/admission"
+	"github.com/basecamp/basecamp-cli/internal/connector/driver/acp"
 	"github.com/basecamp/basecamp-cli/internal/connector/setup"
 )
 
@@ -193,3 +194,33 @@ func TestTheDoctorCheckReadsTheProfilesConnectorLayout(t *testing.T) {
 	assert.Equal(t, "warn", check.Status)
 	assert.Contains(t, check.Hint, "XDG_RUNTIME_DIR", "and says what to do about it")
 }
+
+func TestConnectDriverRunsTheWorkersPinnedACPAdapterFromWhereItWasInstalled(t *testing.T) {
+	d, err := connectDriver(setup.DriverSpawn, setup.WorkerClaude, "")
+	require.NoError(t, err)
+	assert.Equal(t, setup.WorkerClaude, d.Name())
+
+	dir := t.TempDir()
+	_, err = connectDriver(setup.DriverACP, setup.WorkerClaude, dir)
+	require.ErrorIs(t, err, acp.ErrAdapterMissing, "an adapter that is not installed is never fetched")
+
+	pkg := filepath.Join(dir, "node_modules", filepath.FromSlash(acp.ClaudeAgentACP.Package))
+	require.NoError(t, os.MkdirAll(pkg, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(pkg, "package.json"),
+		[]byte(`{"name":"`+acp.ClaudeAgentACP.Package+`","version":"`+acp.ClaudeAgentACP.Version+`"}`), 0o600))
+	bin := filepath.Join(dir, "node_modules", ".bin")
+	require.NoError(t, os.MkdirAll(bin, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(bin, acp.ClaudeAgentACP.Name), []byte("#!/bin/sh\n"), 0o700))
+	d, err = connectDriver(setup.DriverACP, setup.WorkerClaude, dir)
+	require.NoError(t, err)
+	assert.Equal(t, acp.Name, d.Name())
+
+	// A relative directory is the operator's, from where they run the command.
+	t.Chdir(filepath.Dir(dir))
+	d, err = connectDriver(setup.DriverACP, setup.WorkerClaude, filepath.Base(dir))
+	require.NoError(t, err)
+	assert.Equal(t, acp.Name, d.Name())
+
+	_, err = connectDriver(setup.DriverACP, "nobody", dir)
+	assert.Error(t, err)
+}