Add provider project and environment context support

Author: marcusschiesser

.changeset/add-files-sdk-storage.md

@@ -0,0 +1,7 @@
+---
+"@agentpond/files-sdk": minor
+"@agentpond/core": minor
+"agentpond": minor
+---
+
+Add Files SDK span export and persistent bucket-backed CLI sync environments.

AGENTS.md

@@ -38,7 +38,7 @@ This repository uses Changesets to generate package changelogs.
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **agentpond** (1333 symbols, 3159 relationships, 106 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **agentpond** (1524 symbols, 3645 relationships, 121 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** (1333 symbols, 3159 relationships, 106 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **agentpond** (1524 symbols, 3645 relationships, 121 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).
 

apps/cli/package.json

@@ -30,13 +30,15 @@
 		"@agentpond/duckdb": "workspace:*",
 		"@agentpond/fastify-ingest": "workspace:*",
 		"@agentpond/firebase": "workspace:*",
+		"@agentpond/files-sdk": "workspace:*",
 		"@agentpond/google": "workspace:*",
 		"@agentpond/supabase": "workspace:*",
 		"@agentpond/vercel": "workspace:*",
 		"@duckdb/node-api": "^1.5.4-r.1",
 		"@inquirer/prompts": "8.5.2",
 		"commander": "15.0.0",
 		"fastify": "^5.6.2",
+		"files-sdk": "2.2.1",
 		"protobufjs": "^7.6.5",
 		"skills": "1.5.9",
 		"zod": "^4.3.6"

apps/cli/src/commands/env.ts

@@ -1,15 +1,17 @@
 import { existsSync } from "node:fs";
 import {
 	type AgentPondStoreType,
+	type FilesSdkEnvironmentConfig,
 	initAgentPondEnvironment,
 	listAgentPondEnvironments,
 	parseEnvFileEntries,
 	readDevServerLock,
 	resolveAgentPondEnvironment,
 	selectAgentPondEnvironment,
 } from "@agentpond/core";
-import { select } from "@inquirer/prompts";
+import { input, select } from "@inquirer/prompts";
 import type { Command } from "commander";
+import { getProvider, PROVIDER_NAMES } from "files-sdk/providers";
 import { CliError, print } from "../cli-support.js";
 import { addGlobalOptions, type GlobalOptions } from "../command-support.js";
 import {
@@ -32,22 +34,33 @@ export type SelectPrompt<T extends string> = (config: {
 export type SelectEnvironmentPrompt = SelectPrompt<string>;
 export type AgentPondInitStore = AgentPondStoreType;
 export type SelectStorePrompt = SelectPrompt<AgentPondInitStore>;
+export type SelectFilesProviderPrompt = SelectPrompt<string>;
+export type InputPrompt = (config: {
+	message: string;
+	default?: string;
+}) => Promise<string>;
 
 type EnvOptions = GlobalOptions & {
+	bucket?: string;
 	langfuse?: boolean;
 	otel?: boolean;
+	provider?: string;
 	store?: string;
 };
 
 export function registerEnvCommand(
 	program: Command,
 	options: {
 		selectEnvironment?: SelectEnvironmentPrompt;
+		selectFilesProvider?: SelectFilesProviderPrompt;
 		selectStore?: SelectStorePrompt;
+		inputBucket?: InputPrompt;
 	} = {},
 ): void {
 	const promptSelect = options.selectEnvironment ?? select<string>;
 	const promptStore = options.selectStore ?? select<AgentPondInitStore>;
+	const promptFilesProvider = options.selectFilesProvider ?? select<string>;
+	const promptBucket = options.inputBucket ?? input;
 	const env = addGlobalOptions(
 		program.command("env").description("select and manage environments"),
 	);
@@ -100,7 +113,9 @@ export function registerEnvCommand(
 
 	addGlobalOptions(env.command("init <name>"))
 		.description("initialize a manual environment")
-		.option("--store <store>", "object store: s3, gcs, or local")
+		.option("--store <store>", "object store: files-sdk, s3, gcs, or local")
+		.option("--provider <provider>", "Files SDK bucket provider")
+		.option("--bucket <bucket>", "Files SDK bucket name")
 		.action(
 			async (name: string, commandOptions: EnvOptions, command: Command) => {
 				const globalOptions = command.optsWithGlobals<GlobalOptions>();
@@ -111,15 +126,25 @@ export function registerEnvCommand(
 				const store =
 					storeFromValue(commandOptions.store) ??
 					(await promptForStore(promptStore));
+				const filesSdk = await filesSdkConfigForStore(
+					store,
+					commandOptions,
+					promptFilesProvider,
+					promptBucket,
+				);
 				const environment = initAgentPondEnvironment(name, {
 					cwd: context.rootDir,
 					storeType: store,
+					filesSdk: filesSdk?.config,
 				});
 				return print(
 					{
+						bucket: filesSdk?.config.bucket,
 						name: environment.name,
 						envFile: environment.envFilePath,
 						dbPath: environment.dbPath,
+						peerDependencies: filesSdk?.peerDependencies,
+						provider: filesSdk?.config.provider,
 						store,
 					},
 					Boolean(globalOptions.json),
@@ -178,10 +203,17 @@ function storeFromValue(
 	value: string | undefined,
 ): AgentPondInitStore | undefined {
 	if (value === undefined) return undefined;
-	if (value === "s3" || value === "gcs" || value === "local") {
+	if (
+		value === "files-sdk" ||
+		value === "s3" ||
+		value === "gcs" ||
+		value === "local"
+	) {
 		return value;
 	}
-	throw new CliError(`--store must be s3, gcs, or local, got "${value}"`);
+	throw new CliError(
+		`--store must be files-sdk, s3, gcs, or local, got "${value}"`,
+	);
 }
 
 async function promptForStore(
@@ -193,13 +225,96 @@ async function promptForStore(
 	return promptSelect({
 		message: "Select AgentPond object store",
 		choices: [
+			{ name: "Files SDK bucket provider", value: "files-sdk" },
 			{ name: "AWS S3 (or compatible)", value: "s3" },
 			{ name: "Google Cloud Storage (GCS)", value: "gcs" },
 			{ name: "Local filesystem", value: "local" },
 		],
 	});
 }
 
+async function filesSdkConfigForStore(
+	store: AgentPondInitStore,
+	options: Pick<EnvOptions, "bucket" | "provider">,
+	promptProvider: SelectFilesProviderPrompt,
+	promptBucket: InputPrompt,
+): Promise<
+	| {
+			config: FilesSdkEnvironmentConfig;
+			peerDependencies: readonly string[];
+	  }
+	| undefined
+> {
+	if (store !== "files-sdk") {
+		if (options.provider !== undefined || options.bucket !== undefined) {
+			throw new CliError("--provider and --bucket require --store files-sdk");
+		}
+		return undefined;
+	}
+
+	const provider =
+		options.provider ?? (await promptForFilesProvider(promptProvider));
+	const definition = bucketProvider(provider);
+	const bucket = (
+		options.bucket ?? (await promptForFilesBucket(promptBucket))
+	).trim();
+	if (!bucket) throw new CliError("Missing --bucket");
+
+	return {
+		config: { provider, bucket },
+		peerDependencies: definition.peerDeps,
+	};
+}
+
+async function promptForFilesProvider(
+	promptSelect: SelectFilesProviderPrompt,
+): Promise<string> {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		throw new CliError("Missing --provider");
+	}
+	return promptSelect({
+		message: "Select Files SDK bucket provider",
+		choices: bucketProviders().map(({ name, slug }) => ({
+			name: `${name} (${slug})`,
+			value: slug,
+		})),
+	});
+}
+
+async function promptForFilesBucket(promptInput: InputPrompt): Promise<string> {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		throw new CliError("Missing --bucket");
+	}
+	return promptInput({
+		message: "Files SDK bucket",
+		default: "agentpond",
+	});
+}
+
+function bucketProvider(provider: string) {
+	const definition = getProvider(provider);
+	if (!definition) {
+		throw new CliError(
+			`Unknown Files SDK provider "${provider}". Bucket providers: ${bucketProviders()
+				.map(({ slug }) => slug)
+				.join(", ")}`,
+		);
+	}
+	if (!definition.env.config?.includes("bucket")) {
+		throw new CliError(
+			`Files SDK provider "${provider}" is not bucket-backed and is not supported by AgentPond`,
+		);
+	}
+	return definition;
+}
+
+function bucketProviders() {
+	return PROVIDER_NAMES.flatMap((provider) => {
+		const definition = getProvider(provider);
+		return definition?.env.config?.includes("bucket") ? [definition] : [];
+	});
+}
+
 async function promptForEnvironmentName(
 	promptSelect: SelectEnvironmentPrompt,
 	cwd: string,

apps/cli/src/environment-context.ts

@@ -5,6 +5,7 @@ import {
 	configFromEnv,
 	objectStoreForConfig as configuredObjectStoreForConfig,
 } from "@agentpond/core";
+import { FilesObjectStore } from "@agentpond/files-sdk";
 import { GcsObjectStore } from "@agentpond/google";
 import { CliError } from "./cli-support.js";
 import { providerForCommand } from "./providers.js";
@@ -63,6 +64,7 @@ function defaultAgentPondEnvironmentContext(
 		async resolveStorage() {
 			return {
 				store: configuredObjectStoreForConfig(config, {
+					"files-sdk": FilesObjectStore.fromEnvironment,
 					gcs: GcsObjectStore.fromEnvironment,
 					s3: S3ObjectStore.fromEnvironment,
 				}),

apps/cli/src/index.ts

@@ -7,8 +7,10 @@ import { CliError } from "./cli-support.js";
 import { addGlobalOptions } from "./command-support.js";
 import { registerDevCommand } from "./commands/dev.js";
 import {
+	type InputPrompt,
 	registerEnvCommand,
 	type SelectEnvironmentPrompt,
+	type SelectFilesProviderPrompt,
 	type SelectStorePrompt,
 } from "./commands/env.js";
 import { registerInitCommand, type SkillsInstaller } from "./commands/init.js";
@@ -30,8 +32,10 @@ const packageJson = require("../package.json") as { version: string };
 export const CLI_VERSION = packageJson.version;
 
 export type ProgramOptions = {
+	inputBucket?: InputPrompt;
 	installSkills?: SkillsInstaller;
 	selectEnvironment?: SelectEnvironmentPrompt;
+	selectFilesProvider?: SelectFilesProviderPrompt;
 	selectStore?: SelectStorePrompt;
 	updateCheck?: CliUpdateCheckOptions | false;
 };
@@ -58,7 +62,9 @@ export function createProgram(options: ProgramOptions = {}): Command {
 	registerInitCommand(program, { installSkills: options.installSkills });
 	registerDevCommand(program);
 	registerEnvCommand(program, {
+		inputBucket: options.inputBucket,
 		selectEnvironment: options.selectEnvironment,
+		selectFilesProvider: options.selectFilesProvider,
 		selectStore: options.selectStore,
 	});
 	registerSyncCommand(program);