agent-relay-server 0.121.5 → 0.122.1

package/runner/src/profile-home.ts

@@ -0,0 +1,260 @@
+import { existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import type { ProvisioningMcpServer, SpawnProvider } from "agent-relay-sdk";
+import { getManifest } from "agent-relay-providers";
+import { profileAllowsRelayFeature, type RunnerSpawnConfig } from "./adapter";
+import { claudeRelayManual } from "./relay-instructions";
+import { providerHomeRootFromEnv } from "./config";
+import { applyClaudeConfigPromptGatePreventions } from "./claude-prompt-gates";
+
+type ProviderHome = {
+  path: string;
+  authLinked: string[];
+};
+
+export function profileUsesHostProviderGlobals(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+  return !config.agentProfile || config.agentProfile.base === "host";
+}
+
+export function profileAllowsHostAssets(
+  config: { agentProfile?: RunnerSpawnConfig["agentProfile"] },
+  asset: "skills" | "plugins",
+): boolean {
+  return profileUsesProviderHostGlobals(config) || Boolean(config.agentProfile?.hostAssets?.[asset]);
+}
+
+export function profileAllowsHostGlobalInstructions(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+  return !config.agentProfile || config.agentProfile.instructions.globalInstructions === "allow";
+}
+
+export function projectConfigProjectionOn(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+  return Boolean(config.agentProfile?.projectSkills || config.agentProfile?.projectSettings);
+}
+
+/** @deprecated Use {@link projectConfigProjectionOn}. */
+export { projectConfigProjectionOn as claudeProjectConfigProjectionOn };
+
+export function profileUsesProviderHostGlobals(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+  return profileUsesHostProviderGlobals(config) && !projectConfigProjectionOn(config);
+}
+
+/** @deprecated Use {@link profileUsesProviderHostGlobals}. */
+export { profileUsesProviderHostGlobals as profileUsesClaudeHostProviderGlobals };
+
+function profileRequiresIsolatedHome(_provider: SpawnProvider, config: RunnerSpawnConfig): boolean {
+  if (!config.agentProfile) return false;
+  if (config.agentProfile.base !== "host") return true;
+  return projectConfigProjectionOn(config);
+}
+
+// #557 — PURE: the isolated provider config home path a launch WILL use, or undefined
+// for a host-base profile (which uses the provider's normal home). The launch assembler
+// computes the home this way to report it + build CLAUDE_CONFIG_DIR/skill/plugin paths
+// without side effects; prepare*ProfileHome creates it at the same path at spawn time.
+export function providerHomePathFor(provider: SpawnProvider, config: RunnerSpawnConfig): string | undefined {
+  if (!profileRequiresIsolatedHome(provider, config)) return undefined;
+  return providerHomePath(provider, config);
+}
+
+// Provisioned file-backed assets need a relay-owned materialization root even for
+// host-base profiles, where the provider's real config home stays in use. This path is
+// only passed explicitly through launch args such as Codex skills.config or Claude
+// --plugin-dir; it does not imply CODEX_HOME/CLAUDE_CONFIG_DIR isolation.
+export function providerProvisioningHomePathFor(provider: SpawnProvider, config: RunnerSpawnConfig): string | undefined {
+  if (!config.agentProfile) return undefined;
+  return providerHomePathFor(provider, config) ?? join(providerHomePath(provider, config), "provisioning");
+}
+
+// First-run bootstrap (provider layer)
+// -------------------------------------
+// Isolated profile homes are keyed by instanceId, so every spawn gets a brand
+// new CLAUDE_CONFIG_DIR / CODEX_HOME — to the provider it always looks like the
+// first time it has ever run, even in a repo we've used before. Without
+// bootstrapping, the CLI stalls on first-run gates (theme/onboarding picker,
+// "do you trust this folder?") and the agent never starts; the runner then sees
+// repeated ~2s exits and gives up. bootstrap<Provider>FirstRun makes a fresh
+// home launch-ready non-interactively, guaranteeing three things:
+//   1. host auth is linked in,
+//   2. first-run / onboarding flags are pre-accepted (where the provider has them),
+//   3. the cwd workspace is trusted.
+// Workspace trust is independent of repoInstructions: "ignore" means don't load
+// the repo's CLAUDE.md / AGENTS.md as behavioral instructions, NOT "don't
+// operate here" — an isolated agent must still read/edit/execute in its own cwd.
+// (claude-rig / host-base launches dodge all of this via onboarded host config +
+// --dangerously-skip-permissions; only isolated homes need the bootstrap.)
+
+// Provider-specific first-run bootstrap hooks, registered at module load.
+type BootstrapHook = (home: string, config: RunnerSpawnConfig) => void;
+const BOOTSTRAP_HOOKS = new Map<string, BootstrapHook>();
+
+// Shared skeleton: gate on isolated-profile, make the instance-keyed home,
+// link auth items from the manifest, and run any registered first-run hook.
+function prepareProviderHome(provider: SpawnProvider, config: RunnerSpawnConfig): ProviderHome | undefined {
+  if (!profileRequiresIsolatedHome(provider, config)) return undefined;
+  const target = providerHomePath(provider, config);
+  mkdirSync(target, { recursive: true });
+  const hook = BOOTSTRAP_HOOKS.get(provider);
+  if (hook) hook(target, config);
+  const manifest = getManifest(provider);
+  const authItems = manifest?.home?.authItems ?? [];
+  const sourceHome = providerSourceHome(provider);
+  const authLinked = linkExistingAuthItems(sourceHome, target, authItems);
+  linkHostGlobalInstructionFiles(sourceHome, target, config);
+  return { path: target, authLinked };
+}
+
+export const prepareCodexProfileHome = (config: RunnerSpawnConfig) => prepareProviderHome("codex", config);
+export const prepareClaudeProfileHome = (config: RunnerSpawnConfig) => prepareProviderHome("claude", config);
+
+function bootstrapCodexFirstRun(codexHome: string, config: RunnerSpawnConfig): void {
+  disableCodexAppsConnectors(codexHome);
+  trustWorkspaceForCodex(codexHome, config);
+}
+
+function bootstrapClaudeFirstRun(claudeHome: string, config: RunnerSpawnConfig): void {
+  if (profileAllowsRelayFeature(config, "context") && !profileAllowsHostGlobalInstructions(config)) {
+    writeClaudeRelayManual(claudeHome);
+  }
+  seedClaudeConfigIfMissing(claudeHome, config);
+}
+
+BOOTSTRAP_HOOKS.set("codex", bootstrapCodexFirstRun);
+BOOTSTRAP_HOOKS.set("claude", bootstrapClaudeFirstRun);
+
+export function providerSourceHome(provider: string): string {
+  const manifest = getManifest(provider);
+  const envVar = manifest?.home?.configDirEnvVar;
+  const configDir = manifest?.home?.configDir ?? `.${provider}`;
+  return (envVar && process.env[envVar]) || join(homedir(), configDir);
+}
+
+function seedClaudeConfigIfMissing(claudeHome: string, config: RunnerSpawnConfig): void {
+  const path = join(claudeHome, ".claude.json");
+  if (existsSync(path)) return;
+  const host = readHostClaudeConfig();
+  const seed = applyClaudeConfigPromptGatePreventions({}, host, config);
+  writeFileSync(path, JSON.stringify(seed, null, 2), { mode: 0o600 });
+}
+
+function readHostClaudeConfig(): Record<string, unknown> | undefined {
+  try {
+    const hostPath = join(homedir(), ".claude.json");
+    if (!existsSync(hostPath)) return undefined;
+    return JSON.parse(readFileSync(hostPath, "utf8")) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+// #662 — the host USER-scope MCP servers: the top-level `mcpServers` of `~/.claude.json`.
+// These are the ambient host MCP a host-base Claude auto-loads on EVERY launch when NOT
+// strict (user scope is global across all projects — callmux/qmd/gh on this host). Since
+// the #662 wedge fix makes every managed launch `--strict-mcp-config` (so Claude ignores
+// all on-disk config and never renders the project-`.mcp.json` enable modal), an
+// `mcp.mode:"host"` profile must re-inject these explicitly into `--mcp-config` to keep
+// honoring host mode. Deliberately NOT the project-cwd `.mcp.json` (project scope — the
+// modal's source, which must stay excluded) nor `projects[cwd].mcpServers` (local scope).
+export function hostUserScopeMcpServers(): Record<string, ProvisioningMcpServer> {
+  const servers = readHostClaudeConfig()?.mcpServers;
+  if (!servers || typeof servers !== "object") return {};
+  return servers as Record<string, ProvisioningMcpServer>;
+}
+
+function providerHomePath(provider: SpawnProvider, config: RunnerSpawnConfig): string {
+  const root = providerHomeRootFromEnv();
+  const profileName = sanitizePathPart(config.agentProfile?.name || config.profile || "profile");
+  const instance = sanitizePathPart(config.instanceId || config.runnerId);
+  return join(root, provider, profileName, instance);
+}
+
+function sanitizePathPart(value: string): string {
+  return sanitizeFsName(value, { replacement: "-", collapse: false, maxLen: 120, fallback: "profile" });
+}
+
+function linkExistingAuthItems(sourceHome: string, targetHome: string, items: string[]): string[] {
+  const linked: string[] = [];
+  for (const item of items) {
+    if (linkExistingPath(join(sourceHome, item), join(targetHome, item))) linked.push(item);
+  }
+  return linked;
+}
+
+function linkExistingPath(source: string, target: string): boolean {
+  if (!existsSync(source) || existsSync(target)) return false;
+  symlinkSync(source, target);
+  return true;
+}
+
+function linkHostGlobalInstructionFiles(sourceHome: string, targetHome: string, config: RunnerSpawnConfig): void {
+  if (!profileAllowsHostGlobalInstructions(config)) return;
+  for (const file of config.providerConfig.globalInstructionFiles ?? []) {
+    linkExistingPath(join(sourceHome, file), join(targetHome, file));
+  }
+}
+
+function trustWorkspaceForCodex(codexHome: string, config: RunnerSpawnConfig): void {
+  if (!config.cwd) return;
+  const path = join(codexHome, "config.toml");
+  const project = tomlBasicString(resolve(config.cwd));
+  const section = `[projects.${project}]`;
+  const entry = `${section}\ntrust_level = "trusted"\n`;
+  const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+  if (current.includes(section)) return;
+  const prefix = current.trimEnd();
+  writeFileSync(path, `${prefix ? `${prefix}\n\n` : ""}${entry}`, { mode: 0o600 });
+}
+
+function disableCodexAppsConnectors(codexHome: string): void {
+  const path = join(codexHome, "config.toml");
+  const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const next = withTomlFeatureFlag(current, "apps", false);
+  if (next === current) return;
+  writeFileSync(path, next, { mode: 0o600 });
+}
+
+function withTomlFeatureFlag(input: string, key: string, value: boolean): string {
+  const lines = input.length ? input.split("\n") : [];
+  const headerIndex = lines.findIndex((line) => line.trim() === "[features]");
+  const entry = `${key} = ${value ? "true" : "false"}`;
+  if (headerIndex === -1) {
+    const prefix = input.trimEnd();
+    return `${prefix ? `${prefix}\n\n` : ""}[features]\n${entry}\n`;
+  }
+
+  let sectionEnd = lines.length;
+  for (let i = headerIndex + 1; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    if (/^\s*\[[^\]]+\]\s*(?:#.*)?$/.test(line)) {
+      sectionEnd = i;
+      break;
+    }
+  }
+
+  const flagPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+  for (let i = headerIndex + 1; i < sectionEnd; i += 1) {
+    const line = lines[i] ?? "";
+    if (flagPattern.test(line)) {
+      if (lines[i] === entry) return input;
+      lines[i] = entry;
+      return lines.join("\n");
+    }
+  }
+
+  lines.splice(headerIndex + 1, 0, entry);
+  return lines.join("\n");
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function writeClaudeRelayManual(claudeHome: string): void {
+  const path = join(claudeHome, "CLAUDE.md");
+  writeFileSync(path, claudeRelayManual(), { mode: 0o600 });
+}
+
+function tomlBasicString(value: string): string {
+  return JSON.stringify(value);
+}

package/runner/src/profile-projection.ts

@@ -0,0 +1,305 @@
+import type { AgentProfile, AgentProfileProjectionEntry, AgentProfileProjectionReport, SpawnProvider } from "agent-relay-sdk";
+import { getManifest } from "agent-relay-providers";
+import type { AssembledLaunch } from "./launch-assembly";
+
+// #557 — the projection report DESCRIBES an AssembledLaunch, the same object the adapters
+// turn into launch args. It is no longer a separate re-derivation from the profile, so the
+// report and the real launch share one source of truth and cannot drift: change the
+// assembler and both the args AND this report change together. Every entry below reads a
+// field the assembler actually computed (relay gates, provisioned sets, instruction
+// disposition, vanilla mechanism, config home) — only the not-yet-enforced category modes
+// (mcp/hooks) and the purely-declarative env/permissions read straight off the profile.
+
+interface AgentProfileProjectionInput {
+  assembled: AssembledLaunch;
+  generatedAt?: number;
+}
+
+export function agentProfileProjectionReport(input: AgentProfileProjectionInput): AgentProfileProjectionReport {
+  const { assembled } = input;
+  const { provider } = assembled;
+  const profile = assembled.profile;
+  const generatedAt = input.generatedAt ?? Date.now();
+  const entries: AgentProfileProjectionEntry[] = [];
+  const add = (entry: AgentProfileProjectionEntry) => entries.push(entry);
+
+  add(relayContextEntry(assembled));
+  add(relaySkillsEntry(assembled));
+  add(relayPluginsEntry(assembled));
+  add(relayStatusLineEntry(assembled));
+  add(repoInstructionsEntry(assembled));
+  add(globalInstructionsEntry(assembled));
+  add(mcpEntry(assembled));
+  add(hooksEntry(assembled));
+  add(provisioningSkillsEntry(assembled));
+  add(provisioningPluginsEntry(assembled));
+  add(hostSkillsEntry(assembled));
+  add(hostPluginsEntry(assembled));
+  add(provisioningMcpEntry(assembled));
+  for (const entry of provisioningSkippedEntries(assembled)) add(entry);
+  add(projectMcpEntry(assembled));
+  add(projectSkillsEntry(assembled));
+  add(projectSettingsEntry(assembled));
+  add(sharedMcpEntry(assembled));
+  if (profile) add(filesystemEntry(profile));
+  add(configHomeEntry(assembled));
+  if (assembled.vanilla) add(vanillaLaunchEntry(provider));
+  if (profile) add(envEntry(profile));
+
+  const warnings = entries
+    .filter((entry) => entry.result === "partial" || entry.result === "unsupported")
+    .map((entry) => `${entry.capability}: ${entry.detail}`);
+  const unsupported = entries
+    .filter((entry) => entry.result === "unsupported")
+    .map((entry) => entry.capability);
+
+  return {
+    profileName: profile?.name ?? "default",
+    provider,
+    base: assembled.base,
+    generatedAt,
+    entries,
+    warnings,
+    unsupported,
+  };
+}
+
+function relayContextEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  return a.relayContext
+    ? applied("relay.context", "enabled", "Relay context is injected before Relay-delivered provider turns.")
+    : applied("relay.context", "disabled", "Relay context injection is disabled by the profile.");
+}
+
+function relaySkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const manifest = getManifest(a.provider);
+  const label = manifest?.label ?? a.provider;
+  const hasPluginSurface = Boolean(manifest?.provisioning?.bundledPlugin);
+  if (!hasPluginSurface) {
+    return a.relaySkills
+      ? applied("relay.skills", "enabled", `Bundled Agent Relay ${label} skills are passed through the provider's skill delivery mechanism.`)
+      : applied("relay.skills", "disabled", `Bundled Agent Relay ${label} skills are omitted.`);
+  }
+  return a.relaySkills
+    ? applied("relay.skills", "enabled", `Agent Relay ${label} skills are available through the bundled Relay plugin.`)
+    : applied("relay.skills", "disabled", a.relayPlugin
+      ? `${label} does not expose an independent Relay skill switch; disabling skills requires disabling the Relay plugin.`
+      : `Bundled Agent Relay ${label} plugin dirs are omitted, so Relay plugin-provided skills are unavailable.`);
+}
+
+function relayPluginsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const manifest = getManifest(a.provider);
+  const label = manifest?.label ?? a.provider;
+  const hasPluginSurface = Boolean(manifest?.provisioning?.bundledPlugin);
+  if (hasPluginSurface) {
+    return a.relayPlugin
+      ? applied("relay.plugins", "enabled", `Bundled Agent Relay ${label} plugin dir is passed to ${label}.`)
+      : applied("relay.plugins", "disabled", `Bundled Agent Relay ${label} plugin dirs are omitted.`);
+  }
+  return notApplicable("relay.plugins", a.relaySkills ? "enabled" : "disabled", `${label} Relay integration uses skills/app-server delivery, not a Relay plugin dir.`);
+}
+
+function relayStatusLineEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const manifest = getManifest(a.provider);
+  const label = manifest?.label ?? a.provider;
+  if (a.statusLine) {
+    return applied("relay.statusLine", "enabled", "Agent Relay status-line context probe settings are injected when caller settings allow it.");
+  }
+  const hasPluginSurface = Boolean(manifest?.provisioning?.bundledPlugin);
+  if (hasPluginSurface) {
+    return applied("relay.statusLine", "disabled", "Agent Relay status-line settings are omitted.");
+  }
+  return notApplicable("relay.statusLine", "disabled", `${label} reports context through provider-native events instead of a Relay status-line setting.`);
+}
+
+function repoInstructionsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const disposition = a.instructions.repo;
+  if (disposition === "allow") return applied("instructions.repo", "allow", "Repo-local provider instructions are left available.");
+  if (disposition === "suppressed") {
+    const label = getManifest(a.provider)?.label ?? a.provider;
+    return applied("instructions.repo", "ignore", `Repo project instructions are suppressed: ${label} launches with the vanilla base mechanism (provider-specific suppression of repo instructions).`);
+  }
+  return unsupported("instructions.repo", "ignore", "Repo instruction suppression requires the vanilla base; isolated/minimal do not enforce it at launch yet.");
+}
+
+// #552/#554/#555/#556 — the vanilla base's launch-time host suppression, naming the exact
+// provider mechanism the assembler emitted (Claude --setting-sources "user"; Codex
+// project_doc_max_bytes=0). OS-level admin/managed policy is beyond any client flag and is
+// called out so it isn't mistaken for a leak.
+const VANILLA_MECHANISM: Record<string, { requested: string; detail: string }> = {
+  claude: {
+    requested: "--setting-sources user",
+    detail: "Claude launches the isolated config home under --setting-sources \"user\": host CLAUDE.md (repo + global), host skills/plugins/hooks, and host MCP (.mcp.json / ~/.claude.json) are all excluded; relay-provisioned assets in the home load. Auth, model, and built-in tools work normally. OS-level admin-managed policy still applies.",
+  },
+  codex: {
+    requested: "project_doc_max_bytes=0",
+    detail: "Codex launches with an isolated CODEX_HOME (no host config.toml MCP/hooks) and project_doc_max_bytes=0 (no AGENTS.md project doc, repo or global).",
+  },
+};
+
+function vanillaLaunchEntry(provider: SpawnProvider): AgentProfileProjectionEntry {
+  const label = getManifest(provider)?.label ?? provider;
+  const mechanism = VANILLA_MECHANISM[provider];
+  return applied(
+    "provider.vanilla",
+    mechanism?.requested ?? "active",
+    mechanism?.detail ?? `${label} launches with the vanilla base: an isolated provider config home and provider-specific repo instruction suppression. Auth, model, and built-in tools work normally.`,
+  );
+}
+
+function provisioningSkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const count = a.skills.length;
+  if (!count) return notApplicable("provisioning.skills", "none", "No relay-provisioned skills materialized for this launch.");
+  const names = ` (${a.skills.map((s) => s.name).join(", ")})`;
+  const label = getManifest(a.provider)?.label ?? a.provider;
+  return applied("provisioning.skills", `${count}`, `Relay-provisioned skills materialized for ${label} from the isolated provider config home${names}.`);
+}
+
+function provisioningPluginsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const manifest = getManifest(a.provider);
+  const label = manifest?.label ?? a.provider;
+  const hasPluginSurface = Boolean(manifest?.provisioning?.bundledPlugin);
+  if (!hasPluginSurface) {
+    const declared = (a.profile?.plugins ?? []).filter((p) => p.enabled).length;
+    return notApplicable("provisioning.plugins", `${declared}`, `${label} has no plugin surface; provisioned plugins apply to plugin-capable providers only.`);
+  }
+  const count = a.plugins.length;
+  if (!count) return notApplicable("provisioning.plugins", "none", "No relay-provisioned plugins materialized for this launch.");
+  const names = ` (${a.plugins.map((p) => p.name).join(", ")})`;
+  return applied("provisioning.plugins", `${count}`, `Relay-provisioned plugins passed to ${label} via the plugin dir mechanism${names}.`);
+}
+
+function hostSkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const optedIn = Boolean(a.profile?.hostAssets?.skills);
+  if (!optedIn) return notApplicable("hostAssets.skills", "off", "Host/global skill inheritance is off for this resolved profile.");
+  const label = getManifest(a.provider)?.label ?? a.provider;
+  if (!getManifest(a.provider)?.provisioning?.bundledPlugin) {
+    return notApplicable("hostAssets.skills", "unsupported", `${label} does not expose host skill-dir projection through Agent Relay.`);
+  }
+  if (!a.hostSkills.length) return applied("hostAssets.skills", "none", "Host/global skill inheritance is on, but no valid host skill dirs were found.");
+  const names = a.hostSkills.map((s) => s.name).join(", ");
+  return applied("hostAssets.skills", `${a.hostSkills.length}`, `Host/global skills materialized into Relay's managed ${label} config home (${names}).`);
+}
+
+function hostPluginsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const optedIn = Boolean(a.profile?.hostAssets?.plugins);
+  if (!optedIn) return notApplicable("hostAssets.plugins", "off", "Host/global plugin inheritance is off for this resolved profile.");
+  const label = getManifest(a.provider)?.label ?? a.provider;
+  if (!getManifest(a.provider)?.provisioning?.bundledPlugin) {
+    return notApplicable("hostAssets.plugins", "unsupported", `${label} has no plugin-dir surface for host plugin inheritance.`);
+  }
+  if (!a.hostPluginDirs.length) return applied("hostAssets.plugins", "none", "Host/global plugin inheritance is on, but no host plugin dirs are configured.");
+  return applied("hostAssets.plugins", `${a.hostPluginDirs.length}`, `Host/global plugin dirs passed to ${label} (${a.hostPluginDirs.join(", ")}).`);
+}
+
+function provisioningMcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const names = a.mcp.servers;
+  if (!names.length) return notApplicable("provisioning.mcp", "none", "No relay-provisioned MCP servers materialized for this launch.");
+  const count = `${names.length} server${names.length === 1 ? "" : "s"}`;
+  const providerLabel = getManifest(a.provider)?.label ?? a.provider;
+  return applied("provisioning.mcp", count, `Relay-provisioned MCP servers injected for ${providerLabel} (${names.join(", ")})${a.mcp.strict ? "; strict mode guarantees only declared servers load" : ""}.`);
+}
+
+function provisioningSkippedEntries(a: AssembledLaunch): AgentProfileProjectionEntry[] {
+  return (a.profile?.provisioning?.skipped ?? []).map((item) => partial(
+    `provisioning.${item.kind}.${item.ref}`,
+    item.reason,
+    item.detail,
+  ));
+}
+
+// #667 — project `.mcp.json` projection provenance. `not-applicable` when the profile/spawn
+// didn't opt in (the default); `applied` lists the spawn-cwd servers relay injected through
+// the controlled --mcp-config / -c path (sourced from the project, not ambient host MCP).
+function projectMcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const optedIn = Boolean(a.profile?.projectMcp);
+  const names = a.mcp.projectServers;
+  if (!optedIn) return notApplicable("projectMcp", "off", "Project .mcp.json projection is off (opt in via the projectMcp profile/spawn option).");
+  if (!names.length) return applied("projectMcp", "none", "Project .mcp.json projection is on, but the spawn cwd declared no injectable MCP servers.");
+  const count = `${names.length} server${names.length === 1 ? "" : "s"}`;
+  return applied("projectMcp", count, `Project .mcp.json servers injected for this launch (${names.join(", ")})${a.mcp.strict ? "; survives strict MCP mode" : ""}.`);
+}
+
+function projectSkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const optedIn = Boolean(a.profile?.projectSkills);
+  if (!optedIn) return notApplicable("projectSkills", "off", "Project .claude/skills projection is off (opt in via the projectSkills profile/spawn option).");
+  if (!getManifest(a.provider)?.provisioning?.bundledPlugin) return notApplicable("projectSkills", "unsupported", "Project skills projection applies to plugin-capable providers only.");
+  if (!a.projectSkills.length) return applied("projectSkills", "none", "Project .claude/skills projection is on, but the spawn cwd declared no valid skill dirs.");
+  const names = a.projectSkills.map((s) => s.name).join(", ");
+  return applied("projectSkills", `${a.projectSkills.length}`, `Project .claude skills materialized into Relay's managed Claude config home (${names}); host/global skills are excluded.`);
+}
+
+function projectSettingsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const optedIn = Boolean(a.profile?.projectSettings);
+  if (!optedIn) return notApplicable("projectSettings", "off", "Project .claude/settings.json projection is off (opt in via the projectSettings profile/spawn option).");
+  if (!getManifest(a.provider)?.provisioning?.bundledPlugin) return notApplicable("projectSettings", "unsupported", "Project settings projection applies to plugin-capable providers only.");
+  const ignored = a.projectSettings.ignoredKeys.length ? `; ignored security keys: ${a.projectSettings.ignoredKeys.join(", ")}` : "";
+  return applied("projectSettings", a.projectSettings.keys.length ? `${a.projectSettings.keys.length} keys` : "none", `Project .claude/settings.json was sanitized and injected through --settings; Relay approvalMode/permission gates remain authoritative${ignored}.`);
+}
+
+// #672/#689 — shared host-listener MCP provenance. `applied` reports the per-agent `callmux
+// bridge` route. `not-applicable` means the resolved profile kept shared MCP off (for example a
+// zero-host profile, explicit false, or global kill-switch normalization before launch).
+function sharedMcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const optedIn = Boolean(a.profile?.sharedMcp);
+  const listener = a.mcp.sharedListener;
+  if (!optedIn || !listener) return notApplicable("sharedMcp", "off", "Shared host-listener MCP is off for this resolved profile; non-identity MCP is injected per-agent.");
+  return applied("sharedMcp", "on", `Non-identity MCP (e.g. tokenlean, github) routed through the shared callmux listener (${listener.url}) via a per-agent 'callmux bridge --cwd "$WORKTREE"'; session survives a listener restart, session-cwd isolated. Relay endpoint stays per-agent.`);
+}
+
+function globalInstructionsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const disposition = a.instructions.global;
+  if (disposition === "allow") return applied("instructions.global", "allow", "Host/global provider instructions are left available.");
+  if (disposition === "isolated") return applied("instructions.global", "ignore", `${a.provider} uses an isolated provider config home, so host/global provider instructions are not loaded.`);
+  return unsupported("instructions.global", "ignore", `${a.provider} global instruction isolation requires an isolated provider config home.`);
+}
+
+function mcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const mode = a.profile?.mcp.mode ?? "host";
+  if (mode === "host") return applied("mcp", "host", "Host provider MCP configuration is left available.");
+  if (mode === "none" && a.base !== "host") {
+    return applied("mcp", "none", `${a.provider} uses an isolated provider config home without host MCP configuration.`);
+  }
+  return unsupported("mcp", mode, `${a.provider} MCP category projection is not enforced yet.`);
+}
+
+function hooksEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const mode = a.profile?.hooks.mode ?? "host";
+  if (mode === "host") return applied("hooks", "host", "Host provider hooks are left available.");
+  if (mode === "none" && a.base !== "host") {
+    return applied("hooks", "none", `${a.provider} uses an isolated provider config home without host hook configuration.`);
+  }
+  return unsupported("hooks", mode, `${a.provider} hook category projection is not enforced yet.`);
+}
+
+function filesystemEntry(profile: AgentProfile): AgentProfileProjectionEntry {
+  if (profile.permissions.filesystem === "host") return applied("permissions.filesystem", "host", "No profile-level filesystem boundary requested.");
+  return partial("permissions.filesystem", profile.permissions.filesystem, "Relay constrains spawn cwd through the orchestrator; provider-level filesystem sandbox projection is not complete yet.");
+}
+
+function configHomeEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (!a.configHome) return applied("provider.configHome", "host", "Provider uses the host's normal configuration home.");
+  return applied("provider.configHome", a.base, `${a.provider} is launched with an Agent Relay managed provider config home and linked host auth where available.`);
+}
+
+function envEntry(profile: AgentProfile): AgentProfileProjectionEntry {
+  const count = Object.keys(profile.env).length;
+  return count
+    ? applied("env", `${count} vars`, "Profile environment variables are passed through the orchestrator runner environment.")
+    : applied("env", "none", "No profile environment variables requested.");
+}
+
+function applied(capability: string, requested: string, detail: string): AgentProfileProjectionEntry {
+  return { capability, requested, result: "applied", detail };
+}
+
+function partial(capability: string, requested: string, detail: string): AgentProfileProjectionEntry {
+  return { capability, requested, result: "partial", detail };
+}
+
+function unsupported(capability: string, requested: string, detail: string): AgentProfileProjectionEntry {
+  return { capability, requested, result: "unsupported", detail };
+}
+
+function notApplicable(capability: string, requested: string, detail: string): AgentProfileProjectionEntry {
+  return { capability, requested, result: "not-applicable", detail };
+}

package/runner/src/providers.ts

@@ -0,0 +1,20 @@
+import type { SpawnProvider } from "agent-relay-sdk";
+import type { ProviderAdapter } from "./adapter";
+import { ClaudeAdapter } from "./adapters/claude";
+import { CodexAdapter } from "./adapters/codex";
+
+interface RunnerProviderRegistration {
+  provider: SpawnProvider;
+  createAdapter: () => ProviderAdapter;
+}
+
+const RUNNER_PROVIDERS: Record<string, RunnerProviderRegistration> = {
+  claude: { provider: "claude", createAdapter: () => new ClaudeAdapter() },
+  codex: { provider: "codex", createAdapter: () => new CodexAdapter() },
+};
+
+export function createProviderAdapter(provider: SpawnProvider): ProviderAdapter {
+  const registration = RUNNER_PROVIDERS[provider];
+  if (!registration) throw new Error(`unsupported provider adapter: ${provider}`);
+  return registration.createAdapter();
+}