feat(build-cli): add flub ai command and AI-enabled (Insiders) devcontainer (#27020)

tylerbutler · web-flow · commit 93b679876e5d · 2026-04-14T10:59:19.000-07:00
## Summary

- Adds a `flub ai` command that launches an interactive Copilot SDK
session to help users pick the right agent alias and MCP server
configuration
- Creates a new **AI-enabled (Insiders)** devcontainer profile that
builds the flub CLI from source during prebuild, making `flub ai`
available in the codespace
- Updates the base **AI-enabled** profile: simplifies lifecycle hook
shapes (object → string), adds `COREPACK_ENABLE_DOWNLOAD_PROMPT=0` env
var, and removes `postAttachCommand` that opened Getting Started in VS
Code (unreliable since `code` is not always on PATH)
- Insiders differs from the base by name, `onCreateCommand` chaining
`install-flub.sh`, and `openFiles` path
- Shared files like `launcher-prompt.md` live in `ai-agent/` only; `flub
ai` searches `ai-agent-insiders/` first then falls back to `ai-agent/`
- Adds `FLUB_PERF=1` env var support for oclif performance diagnostics
diff --git a/.devcontainer/README.md b/.devcontainer/README.md
@@ -7,6 +7,7 @@ This repo includes multiple Codespaces/devcontainer profiles under `.devcontaine
 | `Standard` | `.devcontainer/devcontainer.json` | Full-repo development, heavier tasks, and broad day-to-day work. |
 | `Lightweight (Review/Docs)` | `.devcontainer/lightweight/devcontainer.json` | Docs, API review, and focused edits with lower compute requirements. |
 | `AI-enabled` | `.devcontainer/ai-agent/devcontainer.json` | AI-agent-assisted workflows with additional default CLI tooling. |
+| `AI-enabled (Insiders)` | `.devcontainer/ai-agent-insiders/devcontainer.json` | AI-enabled plus the `flub ai` launcher command (builds the flub CLI from source). |
 
 ## Selecting a profile in Codespaces
 
@@ -33,6 +34,41 @@ The devcontainer lifecycle hooks are structured for prebuild optimization:
 | Hook | Purpose | Runs in prebuild? |
 | --- | --- | --- |
 | `onCreateCommand` | Node.js setup (nvm install, corepack enable) | Yes |
-| `postCreateCommand` | Welcome notice (all profiles); AI tooling setup (AI-enabled only) | Yes |
+| `postCreateCommand` | Welcome notice (all profiles); AI tooling setup (AI-enabled profiles) | Yes |
 
 Heavy setup work runs in `onCreateCommand` so it is captured by Codespace prebuilds, making the user-connect experience faster.
+
+## AI-enabled vs. AI-enabled (Insiders)
+
+Insiders is a superset of the base AI-enabled profile. The only differences in the insiders `devcontainer.json` are:
+
+- **`name`** — `"AI-enabled (Insiders)"`
+- **`onCreateCommand`** — chains `install-flub.sh` after `on-create.sh` to build and link the `flub` CLI
+- **`codespaces.openFiles`** — points to the insiders copy of `GETTING_STARTED.md`
+
+Everything else (Dockerfile, runArgs, extensions, features, setup scripts, host requirements) is identical.
+
+### Shared vs. duplicated files
+
+The devcontainer spec does not support config inheritance, so `devcontainer.json` is duplicated across the two profiles. Content files use a **fallback** pattern instead: the `flub ai` command searches `ai-agent-insiders/` first, then falls back to `ai-agent/`. This means files can be placed in one of two ways:
+
+| Strategy | Where to put the file | When to use |
+| --- | --- | --- |
+| **Shared** | `ai-agent/` only | File is identical for both profiles. Insiders inherits it via fallback. |
+| **Overridden** | Both `ai-agent/` and `ai-agent-insiders/` | File differs between profiles (e.g. the insiders version mentions `flub ai`). |
+
+Current layout:
+
+| File | `ai-agent/` | `ai-agent-insiders/` | Notes |
+| --- | --- | --- | --- |
+| `devcontainer.json` | yes | yes | Must exist in both (no inheritance in spec). |
+| `launcher-prompt.md` | yes | — | Shared. Insiders finds it via fallback. |
+| `GETTING_STARTED.md` | yes | yes | Overridden. Insiders version adds the `flub ai` section. |
+| `first-run-notice.txt` | yes | yes | Overridden. Insiders version adds the `flub ai` line. |
+
+### Maintenance rules
+
+- **Shared config changes** (extensions, features, runArgs, host requirements, etc.) must be applied to both `devcontainer.json` files.
+- **Shared content** (like `launcher-prompt.md`) should live in `ai-agent/` only. Do not duplicate it into insiders — the fallback handles it.
+- **To promote an insiders feature to the base profile**, copy the relevant lines from the insiders files into the `ai-agent/` versions, then delete the insiders overrides so they fall back to the now-updated shared copy.
+- **To remove an insiders override**, just delete the file from `ai-agent-insiders/`. The `flub ai` command will find the `ai-agent/` fallback automatically.
diff --git a/.devcontainer/ai-agent-insiders/GETTING_STARTED.md b/.devcontainer/ai-agent-insiders/GETTING_STARTED.md
@@ -0,0 +1,83 @@
+# Getting Started with AI-Enabled Codespace
+
+This codespace is pre-configured for AI-agent-assisted development of the Fluid Framework. It includes [agency](https://aka.ms/agency), [repoverlay](https://github.com/tylerbutler/repoverlay), GitHub CLI, and SSH access.
+
+> For full documentation, see the [AI-enabled Codespace wiki page](https://github.com/microsoft/FluidFramework/wiki/AI%E2%80%90enabled-Codespace).
+
+## First-time Setup
+
+Agency is installed automatically the first time you run `dev`, `claude`, or any agent alias - watch for a browser authentication popup.
+If automatic installation fails, you can install agency manually via `pnpm install:agency`.
+
+> [!NOTE]
+> Agency installation is supported in **VS Code** (desktop or SSH).
+> It may not work in a browser-based Codespace because the OAuth redirect requires a local browser and authentication may not complete correctly.
+
+> [!TIP]
+> After creating a new AI-enabled Codespace you may be prompted to authenticate several times.
+> It may seem excessive, but is expected - just keep clicking through each prompt until they stop.
+
+## Quick Start
+
+If dependencies are not installed yet or you need to reinstall them:
+
+```bash
+pnpm install
+
+# Build everything
+pnpm build
+
+# Build only a specific package and its dependencies
+pnpm fluid-build .
+```
+
+## Not sure which agent to use?
+
+Run `flub ai` — an interactive assistant that asks what you want to do and launches the right agent for you.
+
+## AI Agent Aliases
+
+These aliases are available in all terminal sessions (after installing agency):
+
+### Claude
+
+| Alias | Command | Purpose |
+|---|---|---|
+| `dev` | `repoverlay switch --copy nori && agency claude ... -- --model opus` | Launch Claude optimized for feature work and debugging |
+| `claude` | `repoverlay remove --all && agency claude ... -- --model opus` | General purpose Claude Code agent |
+
+### Copilot
+
+| Alias | Command | Purpose |
+|---|---|---|
+| `copilot` | `agency copilot` | Standard GitHub Copilot |
+| `oce` | `repoverlay switch --copy ff-oce && agency copilot -- --agent ff-oce` | On-Call Engineer workflows |
+
+### Custom MCP Servers
+
+The built-in aliases include at least ADO, WorkIQ, and EngHub MCP servers.
+You can also launch an agent with your own combination of MCP servers using the `--mcp` flag.
+Stack as many as you need (and watch for browser authentication popups).
+
+```bash
+# Claude with an additional Kusto MCP server (ADO, WorkIQ, and EngHub are always included)
+claude --mcp 'kusto --service-uri https://kusto.aria.microsoft.com'
+
+# Copilot with an additional MCP server
+copilot --mcp 'workiq'
+```
+
+> Run `agency mcp --help` to see all available MCP servers and their options.
+
+### Utility
+
+| Alias | Command | Purpose |
+|---|---|---|
+| `ai-reset` | `repoverlay remove --all` | Remove all repoverlay overlays and reset to clean state |
+
+## More Information
+
+- [AI-enabled Codespace wiki](https://github.com/microsoft/FluidFramework/wiki/AI%E2%80%90enabled-Codespace) — Full documentation for this codespace profile
+- [DEV.md](../../DEV.md) — Development setup, build commands, and workflow guide
+- [CONTRIBUTING.md](../../CONTRIBUTING.md) — Contribution guidelines
+- [FluidFramework.com](https://fluidframework.com) — Documentation and API reference
diff --git a/.devcontainer/ai-agent-insiders/devcontainer.json b/.devcontainer/ai-agent-insiders/devcontainer.json
@@ -0,0 +1,72 @@
+// AI-enabled (Insiders) — everything in AI-enabled, plus the flub AI launcher command.
+{
+	"name": "AI-enabled (Insiders)",
+	"build": {
+		"dockerfile": "../Dockerfile",
+		"args": {
+			"NODE_VERSION": "24",
+			// "INSTALL_AGENCY": "true",
+			"INSTALL_REPOVERLAY": "true"
+			// TODO: Figure out the playwright strategy
+			// "INSTALL_PLAYWRIGHT_CLI": "true"
+		}
+	},
+	"runArgs": [
+		"--init",
+		"--security-opt=seccomp=unconfined",
+		"--security-opt=apparmor=unconfined",
+		"--cap-add=SYS_ADMIN"
+	],
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"biomejs.biome",
+				"dbaeumer.vscode-eslint",
+				"esbenp.prettier-vscode",
+				"MAI-EngineeringSystems.mai-ai-telemetry",
+				"ms-azure-devops.azure-pipelines",
+				"ms-azuretools.vscode-docker",
+				"mutantdino.resourcemonitor",
+				"vsls-contrib.codetour"
+			],
+			"settings": {
+				"workbench.startupEditor": "none"
+			}
+		},
+		"codespaces": {
+			"openFiles": [".devcontainer/ai-agent-insiders/GETTING_STARTED.md"]
+		}
+	},
+	"containerEnv": {
+		"NODE_VERSION_OVERRIDE": "24",
+		"COREPACK_ENABLE_DOWNLOAD_PROMPT": "0"
+	},
+	"onCreateCommand": "bash scripts/codespace-setup/on-create.sh && bash scripts/codespace-setup/install-flub.sh",
+	"postCreateCommand": "bash scripts/codespace-setup/ai-setup.sh",
+	"postStartCommand": {
+		"bwrap-setup": "sudo mount --make-rshared /",
+		"sandbox-tmpdir": "mkdir -p /tmp/claude"
+	},
+	"postAttachCommand": {},
+	"remoteUser": "node",
+	"features": {
+		// Enables docker CLI inside the container
+		"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
+			"moby": false
+		},
+		// Install the github CLI
+		"ghcr.io/devcontainers/features/github-cli:1": {},
+		// Install git lfs
+		"ghcr.io/devcontainers/features/git-lfs:1": {},
+		// Enables SSH connections into the container using `gh codespace ssh`
+		"ghcr.io/devcontainers/features/sshd:1": {
+			"version": "latest"
+		}
+	},
+	// Setting this so Codespaces default settings use it. It's not really *required*, but a clean build
+	// can be lengthy enough that it's convenient.
+	"hostRequirements": {
+		"cpus": 32,
+		"memory": "64gb"
+	}
+}
diff --git a/.devcontainer/ai-agent-insiders/first-run-notice.txt b/.devcontainer/ai-agent-insiders/first-run-notice.txt
@@ -0,0 +1,27 @@
+ _________   _____       __    __    _____   ______       ________    ________
+(_   _____) (_   _)      ) )  ( (   (_   _) (_  __ \     /_______/\  /_______/\
+  ) (___      | |       ( (    ) )    | |     ) ) \ \    \::: _  \ \ \__.::._\/
+ (   ___)     | |        ) )  ( (     | |    ( (   ) )    \::(_)  \ \   \::\ \
+  ) (         | |   __  ( (    ) )    | |     ) )  ) )     \:: __  \ \  _\::\ \__
+ (   )      __| |___) )  ) \__/ (    _| |__  / /__/ /       \:.\ \  \ \/__\::\__/\
+  \_/       \________/   \______/   /_____( (______/         \__\/\__\/\________\/
+
+GET STARTED: Run one of the commands below:
+  flub ai                Not sure? An AI assistant picks the right agent for you
+  dev                    Launch an agent for feature work/testing/debugging
+  claude                 Launch an agent for general purpose work
+
+Other agent aliases:
+  copilot                Launch GitHub Copilot via agency
+  oce                    Launch Copilot for on-call engineer workflows
+
+Custom MCP servers:
+  See GETTING_STARTED.md for how to launch agents with your own MCP servers.
+
+Other commands:
+  pnpm install           Install all dependencies
+  pnpm build             Build all packages
+  pnpm test              Run tests
+  pnpm fluid-build .     Build only the current package and its dependencies
+
+More information on this codespace: https://github.com/microsoft/FluidFramework/wiki/AI%E2%80%90enabled-Codespace
diff --git a/.devcontainer/ai-agent/devcontainer.json b/.devcontainer/ai-agent/devcontainer.json
@@ -38,21 +38,16 @@
 		}
 	},
 	"containerEnv": {
-		"NODE_VERSION_OVERRIDE": "24"
-	},
-	"onCreateCommand": {
-		"node-setup": "bash scripts/codespace-setup/on-create.sh"
-	},
-	"postCreateCommand": {
-		"ai-setup": "bash scripts/codespace-setup/ai-setup.sh"
+		"NODE_VERSION_OVERRIDE": "24",
+		"COREPACK_ENABLE_DOWNLOAD_PROMPT": "0"
 	},
+	"onCreateCommand": "bash scripts/codespace-setup/on-create.sh",
+	"postCreateCommand": "bash scripts/codespace-setup/ai-setup.sh",
 	"postStartCommand": {
 		"bwrap-setup": "sudo mount --make-rshared /",
 		"sandbox-tmpdir": "mkdir -p /tmp/claude"
 	},
-	"postAttachCommand": {
-		"open-getting-started": "code .devcontainer/ai-agent/GETTING_STARTED.md"
-	},
+	"postAttachCommand": {},
 	"remoteUser": "node",
 	"features": {
 		// Enables docker CLI inside the container
diff --git a/.devcontainer/ai-agent/launcher-prompt.md b/.devcontainer/ai-agent/launcher-prompt.md
@@ -0,0 +1,43 @@
+---
+model: claude-haiku-4-5-20251001
+---
+
+You are a launcher assistant for the Fluid Framework. Your job is to help the user pick the right AI agent alias and MCP server configuration for their task.
+
+## Your Behavior
+1. Greet the user briefly and ask what they want to accomplish today.
+2. Ask clarifying questions if needed to understand their task, one question at a time.
+3. Once you know enough, call select_alias with your recommendation.
+4. NEVER recommend aliases that don't exist in the alias definitions below.
+5. Keep the conversation short — usually 1-2 questions is enough.
+
+## Alias Definitions (source of truth)
+
+The following shell script defines the available aliases. Each shell function IS an alias.
+Study the function bodies to understand what each alias does (which agent it launches,
+which overlays it applies, which MCP servers it includes by default).
+
+```bash
+{{aliasFileContent}}
+```
+
+## Getting Started Guide
+
+The following guide is shown to users when they first start working.
+Use it to understand the aliases, MCP server options, and recommended workflows.
+
+{{gettingStartedContent}}
+
+## Guidelines
+- ONLY recommend aliases that exist as functions in the alias definitions above.
+- When calling select_alias, the alias value must exactly match a function name from the script.
+- Most developers doing feature work should use `dev`.
+- For OCE/incident work, always recommend `oce`.
+- For general questions or exploration without a specific workflow, recommend `claude`.
+- Only suggest `ai-reset` if the user explicitly mentions overlay problems.
+- Don't overload with MCP servers — only suggest extras if the task clearly needs them.
+- When in doubt between `dev` and `claude`, prefer `dev` for any coding task.
+
+---
+
+Begin now. Greet the user and ask what they'd like to do today.
diff --git a/build-tools/packages/build-cli/README.md b/build-tools/packages/build-cli/README.md
@@ -32,6 +32,7 @@ USAGE
 <!-- commands -->
 # Command Topics
 
+* [`flub ai`](docs/ai.md) - AI-powered assistant for launching the right AI agent.
 * [`flub autocomplete`](docs/autocomplete.md) - Display autocomplete installation instructions.
 * [`flub build-perf`](docs/build-perf.md) - Build performance observability commands for collecting, processing, and analyzing build metrics.
 * [`flub bump`](docs/bump.md) - Bump the version of packages, release groups, and their dependencies.
diff --git a/build-tools/packages/build-cli/bin/dev.js b/build-tools/packages/build-cli/bin/dev.js
@@ -4,6 +4,10 @@
  * Licensed under the MIT License.
  */
 
-import { execute } from "@oclif/core";
+import { execute, settings } from "@oclif/core";
+
+if (process.env.FLUB_PERF === "1") {
+	settings.performanceEnabled = true;
+}
 
 await execute({ development: true, dir: import.meta.url });
diff --git a/build-tools/packages/build-cli/bin/run.js b/build-tools/packages/build-cli/bin/run.js
@@ -4,6 +4,10 @@
  * Licensed under the MIT License.
  */
 
-import { execute } from "@oclif/core";
+import { execute, settings } from "@oclif/core";
+
+if (process.env.FLUB_PERF === "1") {
+	settings.performanceEnabled = true;
+}
 
 await execute({ dir: import.meta.url });
diff --git a/build-tools/packages/build-cli/docs/ai.md b/build-tools/packages/build-cli/docs/ai.md
@@ -0,0 +1,41 @@
+`flub ai`
+=========
+
+AI-powered assistant for launching the right AI agent.
+
+* [`flub ai`](#flub-ai)
+
+## `flub ai`
+
+AI-powered assistant that helps you launch the right AI agent.
+
+```
+USAGE
+  $ flub ai [-v | --quiet] [--aliasFile <value>] [--githubToken <value>] [--model <value>]
+
+FLAGS
+  --aliasFile=<value>    [env: FLUB_AI_ALIAS_FILE] Path to the agent-aliases.sh file. Defaults to the AI-enabled
+                         Codespace locations.
+  --githubToken=<value>  [env: COPILOT_GITHUB_TOKEN] GitHub token for the launcher assistant. Defaults to
+                         COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN.
+  --model=<value>        The AI model to use for the launcher assistant. Defaults to the model specified in
+                         launcher-prompt.md frontmatter.
+
+LOGGING FLAGS
+  -v, --verbose  Enable verbose logging.
+      --quiet    Disable all logging.
+
+DESCRIPTION
+  AI-powered assistant that helps you launch the right AI agent.
+
+EXAMPLES
+  Launch the AI assistant to help pick the right agent.
+
+    $ flub ai
+
+  Use a specific model for the launcher assistant.
+
+    $ flub ai --model claude-sonnet-4.5
+```
+
+_See code: [src/commands/ai.ts](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/src/commands/ai.ts)_
diff --git a/build-tools/packages/build-cli/package.json b/build-tools/packages/build-cli/package.json
@@ -90,6 +90,7 @@
 		"@fluid-tools/version-tools": "workspace:~",
 		"@fluidframework/build-tools": "workspace:~",
 		"@fluidframework/bundle-size-tools": "workspace:~",
+		"@github/copilot-sdk": "^0.2.2",
 		"@inquirer/prompts": "^8.0.1",
 		"@microsoft/api-extractor": "^7.58.1",
 		"@oclif/core": "^4.8.0",
@@ -225,6 +226,9 @@
 		"repositoryPrefix": "<%- repo %>/blob/main/build-tools/packages/build-cli/<%- commandPath %>",
 		"topicSeparator": " ",
 		"topics": {
+			"ai": {
+				"description": "AI-powered assistant for launching the right AI agent."
+			},
 			"build-perf": {
 				"description": "Build performance observability commands for collecting, processing, and analyzing build metrics."
 			},
diff --git a/build-tools/packages/build-cli/src/commands/ai.ts b/build-tools/packages/build-cli/src/commands/ai.ts
diff --git a/build-tools/packages/build-cli/src/library/ai/copilotSession.ts b/build-tools/packages/build-cli/src/library/ai/copilotSession.ts
diff --git a/build-tools/packages/build-cli/src/test/commands/ai.test.ts b/build-tools/packages/build-cli/src/test/commands/ai.test.ts
diff --git a/build-tools/pnpm-lock.yaml b/build-tools/pnpm-lock.yaml
diff --git a/scripts/codespace-setup/install-flub.sh b/scripts/codespace-setup/install-flub.sh
