Refactor AgentPond CLI provider and environment handling

Author: marcusschiesser

.changeset/bright-vercel-setup.md

@@ -0,0 +1,8 @@
+---
+"agentpond": minor
+"@agentpond/core": minor
+"@agentpond/firebase": minor
+"@agentpond/vercel": minor
+---
+
+Add automatic Vercel setup with target-aware direct span export to private Blob storage and provider-aware environment selection.

AGENTS.md

@@ -15,6 +15,14 @@ This repository uses Changesets to generate package changelogs.
 - Keep `skills/agentpond/SKILL.md` and `skills/agentpond/references/cli.md` in sync with CLI behavior changes.
 - When a PR changes commands, flags, prompts, environment variables, or storage setup, update the skill in the same PR.
 
+## Provider, Project, and Environment Context
+
+- A provider is the static platform adapter registered by the CLI. It supplies platform metadata and opens a detected provider project from the current directory. Opening a project may succeed before the project is fully linked or configured.
+- A provider project is the project-bound handle returned by `provider.openProject()`. It owns the detected root and setup label, persistent environment selection, and environment resolution, so commands do not repeatedly pass `cwd` through unrelated provider methods.
+- An environment context is the resolved, per-command data-access state for one selected environment. It contains the project root, AgentPond configuration, local cache path, and lazy object-storage resolution. Resolving one may require provider-specific linking or configuration.
+- Keep the CLI provider registry, supported-platform parsing, and provider setup selection in `apps/cli/src/providers.ts`. Do not add provider-specific branches to `apps/cli/src/environment-context.ts`.
+- Use the provider registry to open a provider project for setup and for rejecting provider-managed projects before full resolution. Use the project handle for environment selection and use an environment context for commands that need resolved cache or storage state.
+
 ## Duplicate Code
 
 - Use the `$dry-refactoring` skill when analyzing or fixing duplicate-code findings.
@@ -30,7 +38,7 @@ This repository uses Changesets to generate package changelogs.
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **agentpond** (1244 symbols, 2914 relationships, 98 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **agentpond** (1323 symbols, 3121 relationships, 105 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > Index stale? Run `node .gitnexus/run.cjs analyze` from the project root — it auto-selects an available runner. No `.gitnexus/run.cjs` yet? `npx gitnexus analyze` (npm 11 crash → `npm i -g gitnexus`; #1939).
 

CLAUDE.md

@@ -1,7 +1,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **agentpond** (1244 symbols, 2914 relationships, 98 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **agentpond** (1323 symbols, 3121 relationships, 105 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > Index stale? Run `node .gitnexus/run.cjs analyze` from the project root — it auto-selects an available runner. No `.gitnexus/run.cjs` yet? `npx gitnexus analyze` (npm 11 crash → `npm i -g gitnexus`; #1939).
 

README.md

@@ -14,30 +14,30 @@
   <a href="https://www.npmjs.com/package/agentpond"><img src="https://img.shields.io/node/v/agentpond.svg" alt="Node.js version"></a>
 </p>
 
-AgentPond is a lightweight trace backend and CLI for AI applications. It keeps raw traces in object storage you control and syncs them into a local DuckDB cache for fast analysis by developers and coding agents. Use it with Firebase Storage, Amazon S3, Google Cloud Storage, Vercel Blob, or custom infrastructure. Firebase includes an automated one-command setup; other deployments use the manual setup path.
+AgentPond is a lightweight trace backend and CLI for AI applications. It keeps raw traces in object storage you control and syncs them into a local DuckDB cache for fast analysis by developers and coding agents. Use it with Firebase Storage, Amazon S3, Google Cloud Storage, Vercel Blob, or custom infrastructure. Firebase and Vercel include automated setup; other deployments use the manual setup path.
 
 ## How it works
 
 ![AgentPond data flow from agent traces through object storage and local CLI analysis](https://raw.githubusercontent.com/marcusschiesser/agentpond/main/docs/assets/agentpond-how-it-works.png)
 
 Object storage is the durable source of truth. The local DuckDB database is a rebuildable analytical cache, so production traces stay in your infrastructure without requiring an always-on analytics database.
 
-## Quick start: Firebase in one command
+## Getting started
 
-You need Node.js 22 or newer and an initialized Firebase project with an active project selected through `firebase use`.
+Start with the [Manual deployment setup](./docs/getting-started/manual-setup.md) to choose a write path, configure object storage, instrument the application, and sync its traces into AgentPond.
 
-From the Firebase project or any nested package, run:
+For Firebase and Vercel, AgentPond also provides automated quick starts:
+
+- [Firebase quick start](./docs/getting-started/firebase.md)
+- [Vercel quick start](./docs/getting-started/vercel.md)
+
+Both require Node.js 22 or newer. From the Firebase or Vercel project, run:
 
 ```sh
 npx agentpond init
 ```
 
-The command detects the Firebase project and installs two project skills:
-
-- `agentpond-instrumentation` teaches a coding agent to add OpenInference tracing and export spans directly with `createFirebaseSpanExporter()`.
-- `agentpond` teaches it to sync and analyze the resulting traces.
-
-After installation, copy the prompt printed by `npx agentpond init` into your coding agent. The agent will inspect the server-side application, propose the matching instrumentation, review Firebase Storage access, implement the change, and verify a real trace.
+The command detects the platform, installs AgentPond's instrumentation and analytics skills, and prints a prompt for your coding agent. The agent inspects the trusted Node.js application, proposes the provider-specific setup, implements it after confirmation, and verifies a real trace.
 
 Once the application has emitted a trace:
 
@@ -46,10 +46,6 @@ npx agentpond sync
 npx agentpond traces list --limit 10
 ```
 
-See [Firebase setup](./docs/getting-started/firebase.md) for prerequisites and troubleshooting.
-
-> For Amazon S3, Google Cloud Storage, Vercel Blob, or custom infrastructure, see [Manual deployment setup](./docs/getting-started/manual-setup.md).
-
 ## Analyze traces
 
 Use focused commands for individual traces and sessions:
@@ -84,6 +80,7 @@ AgentPond does not provide a web UI, hosted trace storage, prompt management, da
 ## Documentation
 
 - [Firebase setup](./docs/getting-started/firebase.md)
+- [Vercel setup](./docs/getting-started/vercel.md)
 - [Manual deployment setup](./docs/getting-started/manual-setup.md)
 - [CLI reference](./docs/cli.md)
 - [Deployment reference](./docs/deployment.md)

apps/cli/src/command-support.ts

@@ -23,7 +23,7 @@ export type CommandContext = {
 
 export function addGlobalOptions(command: Command): Command {
 	return command
-		.option("--env <name>", "use a named AgentPond environment")
+		.option("--env <name>", "use an environment for this command")
 		.option("--json", "print machine-readable JSON output");
 }
 
@@ -62,7 +62,7 @@ function logImplicitEnvironment(
 	json: boolean,
 ): void {
 	if (json || options.env || !config.environment) return;
-	console.error(`Using AgentPond environment: ${config.environment.name}`);
+	console.error(`Using environment: ${config.environment.name}`);
 }
 
 function usesRunningDevCache(config: AgentPondConfig): boolean {

apps/cli/src/commands/dev.ts

@@ -11,7 +11,7 @@ import type { FastifyInstance, FastifyLoggerOptions } from "fastify";
 import { CliError, parsePort } from "../cli-support.js";
 import { addGlobalOptions } from "../command-support.js";
 import { devSdkEnvironment } from "../dev-env.js";
-import { environmentContextForCommand } from "../environment-context.js";
+import { manualEnvironmentContextForCommand } from "../environment-context.js";
 
 type DevOptions = {
 	host?: string;
@@ -31,7 +31,8 @@ export function registerDevCommand(program: Command): void {
 export async function startDevServer(options: DevOptions): Promise<void> {
 	const host = options.host ?? "127.0.0.1";
 	const startPort = parsePort(options.port ?? "4318");
-	const cwd = environmentContextForCommand({ envName: "dev" }).rootDir;
+	const context = manualEnvironmentContextForCommand("dev", { envName: "dev" });
+	const cwd = context.rootDir;
 	const environment = initAgentPondEnvironment("dev", { cwd });
 	selectAgentPondEnvironment(environment.name, { cwd });
 	const devConfig = configFromEnv({

apps/cli/src/commands/env.ts

@@ -18,7 +18,11 @@ import {
 	type EnvVar,
 	filterEnvEntries,
 } from "../dev-env.js";
-import { environmentContextForCommand } from "../environment-context.js";
+import {
+	environmentContextForCommand,
+	manualEnvironmentContextForCommand,
+} from "../environment-context.js";
+import { providerForCommand } from "../providers.js";
 
 export type SelectPrompt<T extends string> = (config: {
 	message: string;
@@ -45,7 +49,7 @@ export function registerEnvCommand(
 	const promptSelect = options.selectEnvironment ?? select<string>;
 	const promptStore = options.selectStore ?? select<AgentPondInitStore>;
 	const env = addGlobalOptions(
-		program.command("env").description("manage local AgentPond environments"),
+		program.command("env").description("select and manage environments"),
 	);
 
 	addGlobalOptions(env.command("current"))
@@ -63,19 +67,21 @@ export function registerEnvCommand(
 		});
 
 	addGlobalOptions(env.command("get <name>"))
-		.description("print shell exports for an environment")
+		.description("print shell exports for a manual environment")
 		.option("--langfuse", "print only Langfuse-compatible SDK exports")
 		.option("--otel", "print only OpenTelemetry SDK exports")
 		.action((name: string, commandOptions: EnvOptions) => {
-			const context = environmentContextForCommand({ envName: name });
+			const context = manualEnvironmentContextForCommand("get", {
+				envName: name,
+			});
 			printEnvironmentExports(name, commandOptions, context.rootDir);
 		});
 
 	addGlobalOptions(env.command("list"))
-		.description("list local environments")
+		.description("list manual environments")
 		.action((_commandOptions: EnvOptions, command: Command) => {
 			const globalOptions = command.optsWithGlobals<GlobalOptions>();
-			const context = environmentContextForCommand({
+			const context = manualEnvironmentContextForCommand("list", {
 				envName: globalOptions.env,
 			});
 			const cwd = context.rootDir;
@@ -89,16 +95,13 @@ export function registerEnvCommand(
 		});
 
 	addGlobalOptions(env.command("init <name>"))
-		.description("initialize an environment")
-		.option("--store <store>", "object store: s3, gcs, vercel, or local")
+		.description("initialize a manual environment")
+		.option("--store <store>", "object store: s3, gcs, or local")
 		.action(
 			async (name: string, commandOptions: EnvOptions, command: Command) => {
-				const context = environmentContextForCommand({ envName: name });
-				if (context.kind !== "agentpond") {
-					throw new CliError(
-						`npx agentpond env init is not available for ${context.kind} projects; the project environment is detected automatically`,
-					);
-				}
+				const context = manualEnvironmentContextForCommand("init", {
+					envName: name,
+				});
 				const store =
 					storeFromValue(commandOptions.store) ??
 					(await promptForStore(promptStore));
@@ -126,36 +129,47 @@ export function registerEnvCommand(
 				_commandOptions: EnvOptions,
 				command: Command,
 			) => {
-				const context = environmentContextForCommand({ envName: name });
-				const selectedName =
-					name ??
-					(await promptForEnvironmentName(promptSelect, context.rootDir));
-				const environment = selectAgentPondEnvironment(selectedName, {
-					cwd: context.rootDir,
-				});
+				const selected = await selectEnvironmentForCommand(name, promptSelect);
 				return print(
-					{ selected: environment.name },
+					{ selected },
 					Boolean(command.optsWithGlobals<GlobalOptions>().json),
 				);
 			},
 		);
 }
 
+async function selectEnvironmentForCommand(
+	name: string | undefined,
+	promptSelect: SelectEnvironmentPrompt,
+): Promise<string> {
+	const providerContext = providerForCommand();
+	if (providerContext) {
+		if (!name) throw new CliError("Missing environment name");
+		try {
+			return await providerContext.project.selectEnvironment(name);
+		} catch (error) {
+			throw new CliError(
+				error instanceof Error ? error.message : String(error),
+			);
+		}
+	}
+
+	const context = environmentContextForCommand({ envName: name });
+	const selectedName =
+		name ?? (await promptForEnvironmentName(promptSelect, context.rootDir));
+	return selectAgentPondEnvironment(selectedName, {
+		cwd: context.rootDir,
+	}).name;
+}
+
 function storeFromValue(
 	value: string | undefined,
 ): AgentPondInitStore | undefined {
 	if (value === undefined) return undefined;
-	if (
-		value === "s3" ||
-		value === "gcs" ||
-		value === "vercel" ||
-		value === "local"
-	) {
+	if (value === "s3" || value === "gcs" || value === "local") {
 		return value;
 	}
-	throw new CliError(
-		`--store must be s3, gcs, vercel, or local, got "${value}"`,
-	);
+	throw new CliError(`--store must be s3, gcs, or local, got "${value}"`);
 }
 
 async function promptForStore(
@@ -169,7 +183,6 @@ async function promptForStore(
 		choices: [
 			{ name: "AWS S3 (or compatible)", value: "s3" },
 			{ name: "Google Cloud Storage (GCS)", value: "gcs" },
-			{ name: "Vercel Blob", value: "vercel" },
 			{ name: "Local filesystem", value: "local" },
 		],
 	});